I quite often do this kind of exploration on my iPhone in Mobile Safari (no need to get my laptop out just to quickly check what shape an API is), which is even less convenient for sending custom headers.
When I was younger, I wanted everything to be absolutely correct and small pragmatic perturbations to a design really irked me.
For the last 12 years I have put the api version in the url, it is unambiguous and has never caused a problem. In-band is best, esp for a public service that is consumed in an ad-hoc manner (wget, curl, any http library you can find). Hell, even include the docs in the response.
I wonder if they might be amenable on that one. (If any GitHub staff is reading this.)
The proposed scheme is fairly similar to Stripe's, and although Stripe mainly uses the `Stripe-Version` header for versioning, its API has also always allowed you to alternatively send a `?_stripe_version=<version>` query parameter which it'll respect.
Stripe's API implementation definitely had its share of legacy cruft that added up and made things more difficult to maintain, but out of all of it, I don't remember having to support that alternative `_stripe_version` parameter ever really being a maintenance headache. The leading underscore made sure that even as the API expanded, it never accidentally collided with parameters on any other endpoint.
Author here. I think this is an interesting suggestion, and one we'll have a chat about internally.
I definitely see the benefit of being able to easily hit the URL from a browser - although I think it's probably only relevant for unauthenticated GET requests.
This definitely seems like a “current GitHub” decision where some project manager chain signed off after being “trained” on the benefits. It has a very Microsoft feel of a technically correct if everything goes right (eg, windows registry) but overly complicated and not something that would survive an open source dev review.
That being said, it’s not the end of the world. It’s just eventually these straws will add up to something really bad.
Reasonable people can differ about the word "convenient," but both Chrome and Firefox offer a "copy as fetch" for any request in the Network tab, enabling playing around with requests and responses in the Console
An alternative answer to this question is: well, if it's basic then you don't care about which version they respond with :-D
I agree with you that it’s useful to be able to explore apis from your browser’s address bar. But exploring an api from mobile safari is too hard core for me.
I frequently perform basic API exploration in my web browser - hitting https://api.github.com/repos/simonw/datasette/commits for example - and there isn't a convenient way to add headers to those requests.
I quite often do this kind of exploration on my iPhone in Mobile Safari (no need to get my laptop out just to quickly check what shape an API is), which is even less convenient for sending custom headers.