News for hackers. Stuff that matters.
Re:API versioning has no “right way” (2017) by slver on Monday April 26, 2021 @10:07AM (#26942622)
> 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.

Re:API versioning has no “right way” (2017) by ben509 on Monday April 26, 2021 @10:56AM (#26943158)
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.

Re:API versioning has no “right way” (2017) by jayd16 on Monday April 26, 2021 @10:47AM (#26943057)
Whats specifically wrong with that? Caching issues?
Re:API versioning has no “right way” (2017) by ProblemFactory on Monday April 26, 2021 @03:06PM (#26946623)
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.

Re:API versioning has no “right way” (2017) by jayd16 on Monday April 26, 2021 @07:20PM (#26949579)
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.

Re:API versioning has no “right way” (2017) by iudqnolq on Monday April 26, 2021 @11:30PM (#26951669)
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?

Re:API versioning has no “right way” (2017) by jayd16 on Tuesday April 27, 2021 @12:03AM (#26951875)
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

Re:API versioning has no “right way” (2017) by glckr on Monday April 26, 2021 @10:42AM (#26943008)
Why is that wrong?
Re:API versioning has no “right way” (2017) by zerkten on Monday April 26, 2021 @11:13AM (#26943358)
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.

Re:API versioning has no “right way” (2017) by slver on Tuesday April 27, 2021 @03:11AM (#26952981)
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).

Re:API versioning has no “right way” (2017) by ccouzens on Monday April 26, 2021 @03:07PM (#26946636)
If the different versions have different parameters but share a path you won't be able to document them using openAPI