Feature Request: Display queried URL and API responses in the pop-up badge preview pages

[HariSekhon]

📋 Description

Hi,

First off I'd like to say I love your work to date, thank you so much, this project is great! :)

I'd like to request that the shields.io website extend the preview pop-up pages to display the full API URL with parameters that shields.io is querying on the remote service, as well as the full raw returned API output (pretty-printed if JSON 🙏🏼) in order to debug errors or unknown statuses that may be returned by the 3rd party API.

This will make it easier for users to figure out if the badge is broken because they entered incorrect parameters, or whether there is some issue with their build or even a new or unrecognized API result from on the 3rd party system.

This will also make it easier for people to submit patches for API results that aren't currently understood or have changed without having to be experts in the code base or reproducing what it is doing as it'll be obvious from the UI.

Thanks very much

Hari

[calebcartwright]

Hello @HariSekhon 👋 Thanks for reaching out with your idea, and for sharing those kind words!

However, I've got to say that I'm pretty strongly opposed to this idea. The Shields.io website is intended for end user consumption, not as development/troubleshooting portal. Even if there weren't substantial implementation issues, I wouldn't want to make that end user experience noisy/confusing by trying to also do the latter.

I'd like to request that the shields.io website extend the preview pop-up pages to display the full API URL with parameters that shields.io is querying on the remote service, as well as the full raw returned API output (pretty-printed if JSON 🙏🏼)

This just isn't practical. The frontend site really isn't any different than pasting the badge url into a web browser or a user embedding the badge url into a readme file. It uses the same img.shields.io/.... url to show the badge previews, and has no more insight about the internal implementation of the corresponding backend badge service than any other consumer.

In theory we could massively extend our existing badge server capabilities to expose inner implementation details over separate REST endpoints, but this just feels wrong and unnecessary. It's fairly common in today's world for an API/endpoint to communicate with other endpoints as part of serving a request, but I've never encountered a case of a service providing API endpoints about such internal dependencies and external interactions.

Such a hypothetical feature set would also increase load on our backend, in cases potentially doubling the traffic we have to throw at the upstream services, and would add undo burden and maintenance overhead on the codebase.

We also have services that have to utilize multiple upstream API endpoints in order to fetch all the requisite data required for the badges, and we also have cases where a badge that feels singular to the end user can actually hit entirely different endpoints depending on small changes to the route (like a sort query parameter).

All of that to say, if someone's interested in understanding what's going on under the hood, then I think it'd be far easier to look at the actual codebase instead.

in order to debug errors or unknown statuses that may be returned by the 3rd party API.

This will make it easier for users to figure out if the badge is broken because they entered incorrect parameters, or whether there is some issue with their build or even a new or unrecognized API result from on the 3rd party system.

Do you have a specific case/example? Our badge service infrastructure already handles unrecognized API responses from the upstream providers explicitly via the schema validation used for all badges. I'm also struggling to imagine how viewing the upstream API response on the Shields.io modal window without looking at the corresponding Shields backend code dealing with that response helps shed any light.

We also put a lot of effort into the badge route and query parameters and corresponding errors to be as explicit and loud as possible about the underlying issue, including end-user-typo scenarios.

These are of course very context driven, so the specific errors are handled on a badge-by-badge basis and it's entirely possible that some don't do this as well as others. If you have any specific badges where you feel the error message with a badge could be improved to better convey to the user that they entered incorrect parameters then please let us know!

This will also make it easier for people to submit patches for API results that aren't currently understood or have changed without having to be experts in the code base or reproducing what it is doing as it'll be obvious from the UI.

We strive to make contributing to Shields as easy as possible, because we absolutely consider it to be a community project If you feel like there's any hurdles, challenges, ambiguities, etc. with our documentation and/or contribution process then we'd love to work with you to improve.

However, I'm struggling again to follow the given rationale here. If someone is going to submit a patch to the codebase then of course by definition they will be in the codebase any way. For example, if a user wants to submit a patch for one of the Codeclimate badges, what does seeing the raw responses from Codeclimate API calls in the badge builder modal window on the website give them over the actual source code in https://github.com/badges/shields/blob/master/services/codeclimate/codeclimate-analysis.service.js?

[chris48s]

I can't find the thread - it is lost to the github ether, but we've discussed something similar to this before, but mainly to help people with constructing queries for the dynamic badges.

I don't think it belongs in the frontend for all users see by default as suggested by the OP (I agree with your point "I wouldn't want to make that end user experience noisy/confusing..." it is detail only a minority of users would care about) but I think a debugging page/endpoint with a query builder (or maybe the MVP is you can put in a badge URL) and it dumps out the same output as npm run badge would make it much easier to:

• Construct queries for the dynamic json/xml/yaml badges
• Debug why a custom endpoint badge isn't working

Trying to debug a non-trivial jsonpath query, using just the SVG output can be really tricky.

It might also make it easier for users to submit higher quality bug reports for certain classes of error (if we ask for it in the issue template), but I would assume that benefit would be marginal - many users wouldn't bother.

This will also make it easier for people to submit patches

If you want to submit a PR to fix something, you will at least need a local checkout of the code. The good news is if you've got that, npm run badge chucks out all the debug info you're asking for (and more) before you need to look at the code. Example: npm run badge https://img.shields.io/appveyor/build/gruntjs/grunt so if you're serious about submitting a fix for something that already exists 🎉

[PyvesB]

Agreed with what past maintainers said, will go ahead and close this issue.