6 ms·

Author here. Unsurprisingly, we did have a lot of internet debate about how the version should be specified (header or path or query param) and we landed on usi

Author here. Unsurprisingly, we did have a lot of internet debate about how the version should be specified (header or path or query param) and we landed on using headers. But, to be completely honest, we didn’t find super strong arguments for any option, so it was just something where we had to be opinionated.

djbusby 4y ago
Why pick date version over semver? (Date versioning fan here)
- Existenceblinks 4y ago
  A silly reason I can think of is Date would last longer than semver. I see some moved on already (e.g. https://gitlab.com/staltz/comver https://gitlab.com/staltz/comver)
prepend 4y ago
No one had a strong opinion on simplicity of “/foo/v2” vs “/foo” with a header variable of “2022-11-28.” That seems really surprising.
- Gigachad 4y ago
  A strong argument is different from a strong opinion. Sounds like there are lots of people who feel strongly but none of them can put up a strong argument showing why one is better than the other.
  - prepend 4y ago
    Simplicity is a pretty strong argument in my mind. This whole thread has been full of arguments against. Not sure how we settle on if they are strong enough. 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.
    - masklinn 4y ago
      > Simplicity is a pretty strong argument in my mind. 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/.
- grey-area 4y ago
  For end users the api should be effectively versionless (i.e backwards compatible in all possible cases). 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.
deleted 4y ago
[deleted]
pyrolistical 4y ago
I think the version should only be in the URL if you intend to support that URL forever. 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
keithnz 4y ago
I went through this debate recently also and also ended up realizing there was no clear cut winner, but we did end up coming down on the same method of using headers. But oddly I get anxiety when I see other APIs that have gone for a different choice! Also considered that maybe could do all 3, or header || query parameter (which we may still do).
prng2021 4y ago
Surely, impact to API consumers was considered in changing to a header based approach. What if a company is using an API proxy like Apigee and now has to go through a change control process to incorporate a new custom header on outbound requests? If the 2 options for passing versioning ended up as a toss up, what arguments for a header based design outweighed the negative impacts to consumers?
simonw 4y ago
I just posted an argument for not-headers here: https://news.ycombinator.com/item?id=33782541 https://news.ycombinator.com/item?id=33782541 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 https://news.ycombinator.com/item?id=33781215
- macintux 4y ago
  I just vouched for it: you’re right, it seems a very reasonable comment.
masklinn 4y ago
One thing is not obvious to me: would the header accept any date and use that as a tie-breaker, or would the header only accept “version” dates? 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.

djbusby 4y ago

Why pick date version over semver? (Date versioning fan here)

Existenceblinks 4y ago
A silly reason I can think of is Date would last longer than semver. I see some moved on already (e.g. https://gitlab.com/staltz/comver https://gitlab.com/staltz/comver)

prepend 4y ago

No one had a strong opinion on simplicity of “/foo/v2” vs “/foo” with a header variable of “2022-11-28.” That seems really surprising.

Gigachad 4y ago
A strong argument is different from a strong opinion. Sounds like there are lots of people who feel strongly but none of them can put up a strong argument showing why one is better than the other.
- prepend 4y ago
  Simplicity is a pretty strong argument in my mind. This whole thread has been full of arguments against. Not sure how we settle on if they are strong enough. 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.
  - masklinn 4y ago
    > Simplicity is a pretty strong argument in my mind. 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/.
grey-area 4y ago
For end users the api should be effectively versionless (i.e backwards compatible in all possible cases). 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.

deleted 4y ago

[deleted]

pyrolistical 4y ago

I think the version should only be in the URL if you intend to support that URL forever. 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

keithnz 4y ago

I went through this debate recently also and also ended up realizing there was no clear cut winner, but we did end up coming down on the same method of using headers. But oddly I get anxiety when I see other APIs that have gone for a different choice! Also considered that maybe could do all 3, or header || query parameter (which we may still do).

prng2021 4y ago

Surely, impact to API consumers was considered in changing to a header based approach. What if a company is using an API proxy like Apigee and now has to go through a change control process to incorporate a new custom header on outbound requests? If the 2 options for passing versioning ended up as a toss up, what arguments for a header based design outweighed the negative impacts to consumers?

simonw 4y ago

I just posted an argument for not-headers here: https://news.ycombinator.com/item?id=33782541 https://news.ycombinator.com/item?id=33782541 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 https://news.ycombinator.com/item?id=33781215

macintux 4y ago
I just vouched for it: you’re right, it seems a very reasonable comment.

masklinn 4y ago

One thing is not obvious to me: would the header accept any date and use that as a tie-breaker, or would the header only accept “version” dates? 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.