interesting. No more /api/v1 or /api/v2 in the urls. Now it's just /api/thing but pass in X-Api-Version in header and the version is a date not a number or 1.2.3 three numbers.
That seems really surprising.
It seems not strong enough for Microsoft. But that’s why I was surprised as being a not very useful hassle would seem to be a big reason not to do it that way.
Cynically, I fear this method allows lots more versions and lots more breaking changes so get ready for stuff that could have been backwards compatible now just be a breaking change with a new version.
But the URL version inly wins that argument if you ignore all the issues.
Github clearly wants to iterate their REST API faster and feels constrained, the URL method would mean either the entire API versions over quickly with almost but not quite copy pastes, or endpoints get versioned individually and you’re simultaneously hitting /3/foo and /42/bar with little rhyme or reason.
Things get confusing when you retrieve an entity via /6/ then update it via /4/.
Most api consumers don’t care if fields are added or new methods added they are not using, thus they don’t care much about the version unless upgrading. Removing things or changing behaviour should be very rare and have a very good justification.
I am of the opinion URLs are a promise the document will be available until the end of time. I don’t want to break the internet with 404s.
Since the only promise here is for the API to exist for 2 years when depreciated, then I think using a header is appropriate.
Query param doesn’t make sense either as it is often used as input data into the document at the URL. The document schema depends on the API version, so query params become a chicken/egg scenario
Short version: I do initial research against APIs using web browsers a LOT, including on my phone, and headers are really inconvenient for that.
In case you can't see DEAD comments, there's one here that talks about this too (and isn't offensive about it, so I imagine the account is DEAD for some other reason): https://news.ycombinator.com/item?id=33781215
Let’s say I start coding against the API today, can I just set the header to “today” and github will dereference that to the nearest preceding version, or do I have to look up and set the header for each endpoint?
IME it’s common to have a “broker” which handles all calls to the API in order to do common ore and post processing, having to look up and specify versions for each call sites would be frustrating, as well as the risk of different calls using different versions.
Sure if I’m writing an integration that’s no big deal, but it makes it more of a PITA to do things from the CLI with curl.
that would be my guess
In essence, they transform requests from the latest API version back to the (older) versions by writing an adapter for each response for every breaking change. Not sure what they do for new endpoints, or when a future response no longer includes a field that used to be included before.
Some nice things though:
- timeline they suggest seems to be longer than GitHub (implied by the “a power company should not change its voltage every 2 years” statement)
- instead of a header, it’s linked to the account of the user and the time of the first API call. That might be a good default for GH rather than the oldest available version at that time as suggested elsewhere in the comments. (drives adoption, least surprise, longest expected validity of the interface)
Edit: formatting
I personally find this a much saner way to declare api versions (version in header). Specially if the platform supports Webhooks which have urls in the payload: if your API declares version in the path, which version do you use in the webhooks urls?
Imagine you release package on npm (or whatever) versioning it with v1 and constantly adding new features and still keeping the v1 version tag. That's what you're doing to your API.
Semantically it is equivalent though.