Document stance on APIs following the endpoint badge schema

[PyvesB]

We've had a few recent contributors wanting to implement native badges using Shields-specific APIs based on our endpoint badge schema (#6368, #6307 and #5701).

This is an attempt at documenting our stance on this matter.

@calebcartwright as you'll notice, I've slightly reused some of your wording here. 😉

Let me know what you think!

[shields-ci]

	Messages
📖	Thanks for contributing to our documentation. We ❤️ our documentarians!
📖	✨ Thanks for your contribution to Shields, @PyvesB!

Generated by 🚫 dangerJS against 121df49

[chris48s]

I kind of know what this is trying to say, but it seems like an oblique way of approaching it and this doesn't really explain why we are saying this. I don't think we are really saying if an upstream service has no use for an API but adds an JSON endpoint specifically for us surfacing the info we need for an integration (but not using the endpoint schema) we wouldn't use it, are we? I think that's pretty much what you told Localazy they had to do to get a PR accepted.. i.e: I think thing thing we don't want to do is potentially take on maintenance of a wrapper/integration test for every endpoint badge is the only 'value-add' is to give it a nicer URL, right?

It is kind of a hard thing to phrase (I'm also struggling slightly). What if we frame it something more like:

The JSON endpoint badge is a allows users to generate bespoke badges with the full power of Shields' badge customization. If a service already provides badges using the JSON endpoint feature, the upstream service and their end users already have access to the full range of shields features. We won't add wrappers for an existing endpoint badge just to give it a 'friendly' URL.

dunno if that is any better?

[PyvesB]

Thanks for the feedback. Will give it another go.

[calebcartwright]

Thanks for starting this dialog. It's definitely been recurring with enough frequency that IMO it'll be helpful to have something where we can point folks (#6327 may be another example). Have been ruminating on this one a bit so apologies for the lack of brevity 😄

I know we're all well aware of this fact, but it's probably also worth noting for posterity that the Shields.io site has turned into a place where developers can discover services that are useful for development/building/analysis/etc. Accordingly there's some understandable motivation for the service maintainers/providers to get native badges included so that their badges are listed and discoverable (I know I came across a couple services I use regularly which I discovered via Shields.io)

I suspect part of the problem is that there's a trend of folks confusing/conflating the Endpoint badge schema as "the" way to get natively integrated in the Shields ecosystem, which isn't really the point of the Endpoint badge.

There's some badge requests that simply aren't feasible to include as native badges, for example those that aren't developer/technologist related services, require user/account-specific authorization details, require page scraping, etc. and which we'd definitely decline/defer to an Endpoint badge. At the same time as Chris noted above, I agree that we wouldn't necessarily want to refuse to add a native badge (at some point) just because the corresponding service's API contract seems based on the Endpoint schema.

I feel like what we want to convey is that we want anything submitted as a native badge to handle the rendering aspects, and only utilize the API response to get the corresponding data point for the particular badge(s) in question (build result, numerical code coverage, etc.) Basically, native badges should utilize the upstream service for the "what", not the "how", if we're dealing with a coverage badge, we want the numerical code coverage value from the upstream source, but Shields doesn't care what the upstream service thinks the color of the badge should be. It doesn't matter to us if the upstream service happens to include aspects of the "how" (badge color, label, etc.) in the response, but those should be ignored. Additionally, we don't want our native badges to have to do extra work to extract the data because of the API response structure is geared towards badge rendering concerns (e.g. for something like test results, we'd strongly prefer a response like { "passedTests": 9, "failedTests": 2 } instead of dealing with something like { "message": "9 passed test(s), 2 failed test(s) }

Maybe it'd be useful to have a doc that's general guidelines for getting a badge incorporated into the Shields ecosystem that's largely targeted at an audience including owners/maintainers of a service as well as an individual contributor that'd like to get a badge for their favorite service/tool. Basically a higher level "How to make a new badge happen" doc that can help folks pick a good path and then guide/point them to the other relevant documentation (i.e. use an Endpoint badge if A, B, or C is true in your case and link out to Endpoint, if native badge then links to guideline, tutorial, API stance, etc.)

I'd think within that type of guide we could codify something relative to our stance on the API structure and contracts, and what the threshold(s) would be for a native badge vs. when an Endpoint (or using our npm package or even just following our badge specification).

Thoughts?

[PyvesB]

I think we're all fundamentally on the same page. The tricky part if how to convey our guidance in a clear and concise manner, which this PR may have failed to do - though I'm still happy to give it another go based on Chris' suggestions. :)

I'm not against a "How to make a new badge happen" doc per say, but in my opinion we should only do that as part as a slightly wider rework of our documentation. Right now our guidance on contributing new badges to Shields.io in scattered all around the place:

• general guidance and aesthetics in the spec.
• slightly more prescriptive guidance here.
• conventions on URL structure here.
• guidance on schema building here.
• the main tutorial which points to some of the above but not all, here.
• the separate service tests guide here.
• some help to get a dev environment set up in the README.
• other places which I've omitted?

Some of these documents are quite lengthy and it may be a bit of a maze to navigate them for new contributors. I guess what I'm saying is that I wouldn't want yet another separate document, as it would potentially make things harder for new contributors and increase the chances of them TLDRing anyway.

Before we add any more, are there opportunities to better streamline, organise or summarise our existing documentation?

[calebcartwright]

Right now our guidance on contributing new badges to Shields.io in scattered all around the place:

Completely agreed, and this is largely the problem I was suggesting we attempt to solve with a singular entry point. The list you collated shows the breadth of topics that have detailed documentation (which makes sense to me given the quantity of topics an depth of detail), but I feel like we're missing a standard start/entry point we could send everyone to.

The concern I'd have is that in the current state it's quite conceivable for a new contributor to miss something important unless they happened to start with on particular doc or read them all

[PyvesB]

I'll close this for now and slowly rework some of the docs, keeping in mind some of the above thoughts.