5 ms·

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.

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.

dottedmag 4y ago
The difference is purely cosmetic: version could have been stuffed into URL as /api/2022-11-28 and nothing would change.
- CharlieDigital 4y ago
  It's much more ergonomic and compact to use as an end user than a dedicated header, IMO.
  - dottedmag 4y ago
    Agreed, pragmatically a separate header is a dubious choice. Semantically it is equivalent though.
chrismeller 4y ago
I also found it odd that they switched from URL versioning to an HTTP header. 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.
- datapolitical 4y ago
  Well, you don’t need the header
  - chrismeller 4y ago
    You don’t need it if you’re expecting the current 2022-11-28 version, but it seems like you’ll need it to “opt-in” to any future ones, which presumably includes new endpoints that don’t even exist in the current.
    - timrogers 4y ago
      Author here. We consider new endpoints to be non-breaking changes, so they’ll be available in 2022-11-28.
      - chrismeller 4y ago
        Ah, ok. Well personally that seems even worse. Adding new things to the existing “version” just seems crazy.
        akoncius 4y ago
        depends on how you define "version" here. seems that github took "version changes when backwards compatibility is broken" version which can mean that you can deploy 20 new features but if those are new then "version" does not change. that would be my guess
- deleted 4y ago
  [deleted]
dividuum 4y ago
Looks pretty similar to Stripe's API versioning method: https://stripe.com/docs/upgrades#api-versions https://stripe.com/docs/upgrades#api-versions
- hectormalot 4y ago
  A great blogpost on the architecture Stripe chose for calendar based versioning: https://stripe.com/blog/api-versioning https://stripe.com/blog/api-versioning 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
  - pbreit 4y ago
    The major problem it seems to me with these versioning approaches is that at some point you want a non-breaking change that arrived after a breaking change. Then what?
  - chucke 4y ago
    Stripe also allows a header to declare the version, which is how you should upgrade (test each endpoint one by one, and when they're all migrated, upgrade the account api version). 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?
timrogers 4y ago
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.
mirzap 4y ago
Finally someone does versioning properly and enforce basic REST principles. URL versioning (v1,v2, etc) simply don't make any sense yet they are used all the time. API shouldn't ever change (on that version) once you release the version, yet we see new endpoints appear after v1/ all the time. You never know what's new what old feature in url versioning. 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.

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.

dottedmag 4y ago

The difference is purely cosmetic: version could have been stuffed into URL as /api/2022-11-28 and nothing would change.

CharlieDigital 4y ago
It's much more ergonomic and compact to use as an end user than a dedicated header, IMO.
- dottedmag 4y ago
  Agreed, pragmatically a separate header is a dubious choice. Semantically it is equivalent though.

chrismeller 4y ago

I also found it odd that they switched from URL versioning to an HTTP header. 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.

datapolitical 4y ago
Well, you don’t need the header
- chrismeller 4y ago
  You don’t need it if you’re expecting the current 2022-11-28 version, but it seems like you’ll need it to “opt-in” to any future ones, which presumably includes new endpoints that don’t even exist in the current.
  - timrogers 4y ago
    Author here. We consider new endpoints to be non-breaking changes, so they’ll be available in 2022-11-28.
    - chrismeller 4y ago
      Ah, ok. Well personally that seems even worse. Adding new things to the existing “version” just seems crazy.
      - akoncius 4y ago
        depends on how you define "version" here. seems that github took "version changes when backwards compatibility is broken" version which can mean that you can deploy 20 new features but if those are new then "version" does not change. that would be my guess
deleted 4y ago
[deleted]

dividuum 4y ago

Looks pretty similar to Stripe's API versioning method: https://stripe.com/docs/upgrades#api-versions https://stripe.com/docs/upgrades#api-versions

hectormalot 4y ago
A great blogpost on the architecture Stripe chose for calendar based versioning: https://stripe.com/blog/api-versioning https://stripe.com/blog/api-versioning 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
- pbreit 4y ago
  The major problem it seems to me with these versioning approaches is that at some point you want a non-breaking change that arrived after a breaking change. Then what?
- chucke 4y ago
  Stripe also allows a header to declare the version, which is how you should upgrade (test each endpoint one by one, and when they're all migrated, upgrade the account api version). 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?

timrogers 4y ago

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.

mirzap 4y ago

Finally someone does versioning properly and enforce basic REST principles. URL versioning (v1,v2, etc) simply don't make any sense yet they are used all the time. API shouldn't ever change (on that version) once you release the version, yet we see new endpoints appear after v1/ all the time. You never know what's new what old feature in url versioning. 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.