3 ms·

> It doesn't really matter how you version. While there are many right ways to version, there are also a few wrong ones. Like putting the version in a header.

by slver 6y ago

glckr 6y ago
Why is that wrong?
- slver 6y ago
  Headers are hard to spot in code examples, in traffic sniffers, in logs, and in this case a version can alter the behavior of an API from subtly to drastically producing endless amount of WTFs for your dev team because they can't easily spot what is going on. We need to strive to make an API obvious and "immutable" (i.e. under one path you get one specific behavior). This in affect means the good old boring /v2/ in the URL path tends to be best if you can't keep everything under one roof by deprecating/removing/introducing single endpoints in the initial version (due to lots of name collisions).
- zerkten 6y ago
  It's in the comment that the person was replying to: "...it will be much easier to run analytics on usage from web access logs..." Headers don't normally get logged the way that URLs do. Having easy and cheap analytics is very helpful in making the right calls. "Expensive" analytics is really painful with APIs because some people rightfully get scared about the impact of making changes while others will just plow ahead.
- ccouzens 6y ago
  If the different versions have different parameters but share a path you won't be able to document them using openAPI
jayd16 6y ago
Whats specifically wrong with that? Caching issues?
- ProblemFactory 6y ago
  Putting the version in a header looks "elegant" at first, as it keeps one URL for one resource. But in reality it adds accidental annoyance with no benefits over having the version somewhere in the URL. * Have to set up response headers and caching carefully to make sure different versions are cached separately. * A bit of extra complexity to set up load balancing. * A bit of extra complexity to set up web framework routing to controllers. * A bit of extra complexity for logging to track which endpoints were called. * Calling the URL without specifying a version gets you some undefined version... * ... or if you require a version header, can't preview GET endpoints in a standard browser. * If different parts of the API have different latest versions, you can't encode it in an URL and therefore can't return URLs for linking between resources. * On major version changes you might be removing, renaming or moving URLs, so why keep them pure and versionless in the first place.
  - jayd16 6y ago
    Still seems like caching is the only real issue. The complexity of dealing with headers seems easier than the complexity of routing constantly changing urls.
    - iudqnolq 6y ago
      Blows up a smaller percentage of the time when you forget it is often worse. How often are your APIs changing incompatibly anyway? When they do changing the URL should dwarf next to changing the surrounding code to the new data model. If that's not the case then what was the point of the upgrade?
      - jayd16 6y ago
        My point is its pretty trivial either way. With headers, you can use the stripe style[1] time stamp version headers that give you a clearer picture of exactly targeting an API as it was at any given time, instead of as it was stated in the url (ie .../vN/...) [1]https://stripe.com/docs/api/versioning https://stripe.com/docs/api/versioning
ben509 6y ago
The wrongest is when it's stuck in an irrelevant header, as in Accept: application/json;v=3 I'm sure that's specified somewhere, but it's a shamefully stupid specification, so don't follow it. Any sane person reading that is going to think you're accepting a specific version of JSON. Also, if you must put versions be in a header, STOP with the nonsense of pretending things don't exist. Give us some freaking clue, return a 404 and explain that we're missing your stupid header, or that the planets haven't aligned, or whatever we're supposed to fix.

> It doesn't really matter how you version. While there are many right ways to version, there are also a few wrong ones. Like putting the version in a header.

by slver 6y ago

> It doesn't really matter how you version. While there are many right ways to version, there are also a few wrong ones. Like putting the version in a header.

glckr 6y ago

Why is that wrong?

slver 6y ago
Headers are hard to spot in code examples, in traffic sniffers, in logs, and in this case a version can alter the behavior of an API from subtly to drastically producing endless amount of WTFs for your dev team because they can't easily spot what is going on. We need to strive to make an API obvious and "immutable" (i.e. under one path you get one specific behavior). This in affect means the good old boring /v2/ in the URL path tends to be best if you can't keep everything under one roof by deprecating/removing/introducing single endpoints in the initial version (due to lots of name collisions).
zerkten 6y ago
It's in the comment that the person was replying to: "...it will be much easier to run analytics on usage from web access logs..." Headers don't normally get logged the way that URLs do. Having easy and cheap analytics is very helpful in making the right calls. "Expensive" analytics is really painful with APIs because some people rightfully get scared about the impact of making changes while others will just plow ahead.
ccouzens 6y ago
If the different versions have different parameters but share a path you won't be able to document them using openAPI

jayd16 6y ago

Whats specifically wrong with that? Caching issues?

ProblemFactory 6y ago
Putting the version in a header looks "elegant" at first, as it keeps one URL for one resource. But in reality it adds accidental annoyance with no benefits over having the version somewhere in the URL. * Have to set up response headers and caching carefully to make sure different versions are cached separately. * A bit of extra complexity to set up load balancing. * A bit of extra complexity to set up web framework routing to controllers. * A bit of extra complexity for logging to track which endpoints were called. * Calling the URL without specifying a version gets you some undefined version... * ... or if you require a version header, can't preview GET endpoints in a standard browser. * If different parts of the API have different latest versions, you can't encode it in an URL and therefore can't return URLs for linking between resources. * On major version changes you might be removing, renaming or moving URLs, so why keep them pure and versionless in the first place.
- jayd16 6y ago
  Still seems like caching is the only real issue. The complexity of dealing with headers seems easier than the complexity of routing constantly changing urls.
  - iudqnolq 6y ago
    Blows up a smaller percentage of the time when you forget it is often worse. How often are your APIs changing incompatibly anyway? When they do changing the URL should dwarf next to changing the surrounding code to the new data model. If that's not the case then what was the point of the upgrade?
    - jayd16 6y ago
      My point is its pretty trivial either way. With headers, you can use the stripe style[1] time stamp version headers that give you a clearer picture of exactly targeting an API as it was at any given time, instead of as it was stated in the url (ie .../vN/...) [1]https://stripe.com/docs/api/versioning https://stripe.com/docs/api/versioning

ben509 6y ago

The wrongest is when it's stuck in an irrelevant header, as in Accept: application/json;v=3 I'm sure that's specified somewhere, but it's a shamefully stupid specification, so don't follow it. Any sane person reading that is going to think you're accepting a specific version of JSON. Also, if you must put versions be in a header, STOP with the nonsense of pretending things don't exist. Give us some freaking clue, return a 404 and explain that we're missing your stupid header, or that the planets haven't aligned, or whatever we're supposed to fix.