How do you handle API versioning?

General Prog (Archived)
1

Hello!

I have a question about a better way to handle a version of your REST API.

I came across a couple of posts (post1, post2) suggesting to use vendor MIME type for that in 2 ways:

  • version inside subtype, like application/vnd.steveklabnik-v2+json;
  • version as mimetype parameter, like vnd.example-com.foo+json; version=1.0

I would be glad to hear about pros and cons of both solutions. Or maybe there is other way?

3 Likes
2

What’s wrong with /api/v1 and /api/v2, e.g. namespacing?

1 Like
3

There is a good argument to be made that versions in the URI are neither good URI design nor RESTful. You want your public facing link to be permanent, an URI in your system should try as much as it can to be exactly that, a Unique Resource Identifier. Having versions in your URIs was never supposed to be a part of the picture.

4 Likes
4

:slight_smile:

5 Likes
5

I’m with @dimitarvp on this one.

Also we are moving towards WebSocket APIs where we don’t have the option to specify version in the header so for me this particular holy war is won by URLs / topics :slight_smile:

3 Likes
6

That’s perfectly ok. All of the 3 common versioning schemes (@BrightEyesDavid article has this explained) have their advantages and disadvantages. If you have to use URL versioning just know what you’re giving up.

1 Like
7

I am not gonna do academic discussions. Half of HTTP 1.1 headers should not even be used the way they are used but here we are.

Versioning by using namespaced URIs solves a lot of problems and gives you an ability to evolve your API instead of being stuck with legacy baggage forever.

1 Like
8

You do you. The way I worded it, I hope, was supposed to convey facts without having my stance figure in it at all.

Having said that, versions in your URL can seriously hamper the evolution of your APIs too. As I already mentioned, all options out there have a trade off, you have to pick the one you think is right for your problem. Dismissing the entire issue by saying it’s academic, I feel, doesn’t do you many favors.

9

Care to give an example? Lots of big companies do that (from the top of my head Twitter, Google, PayPal, DigitalOcean) and seem to cope.

1 Like
10

A version in the URI does not affect permanence, the v1 URI will always get the exact same thing.

1 Like
11

Sure, with that approach you always run into issue of the type: I have a change in one of my resources, does this warrant a version increase?

You will naturally tend to have large releases that increment your version, and then wonder what to do with smaller changes. There is always the risk of small changes creeping into your API without a version change.

12

Sure, with that approach you always run into issue of the type: I have a change in one of my resources, does this warrant a version increase?

Does it matter if you pass version in URL or a header though? You’d have to be able to increase version and fallback to the logic of the previous one no matter how you go about versioning.

13

You are implying that adding one field to a child object as a part of a bigger response will break clients. I have never seen that happening.

Version increases cover large shifts. Minor changes in the API do not at all warrant version increases.

Breaking changes can happen but it’s a rarity. Nobody is in the business of changing APIs every week.

You are assuming much more brittleness than what is practically visible out there. People go out of their way to not make changes break existing clients, quite successfully 99% of the time too.

1 Like
14

This is debatable. You will see APIs move from version 1 to say eventually version 3, then drop support for version 1. All your links now stop working.

There are ways around this, with say redirection. But having a single URL that doesn’t have these issues.

15

This has zero relation to if your API URLs are namespaced or not. Businesses die – or rapidly change course – every day.

Deprecations are a fact of life.

1 Like
16

I was not implying this. And sure, you may have a simple API where this doesn’t happen. But all the discussion there is about this topic may point out that versioning is not such a simple issue. If 99% of APIs handle this successfully as your research points out, then I think that would mean that one way is the absolute correct way and people just don’t have these issues.

Personally, I think people underestimate the entire problem of versioning. Take NPM as an example. It is widely used, didn’t take versioning seriously for a long time, and is still incredibly successful. So don’t let that stop you from using it. But if you are building an API you want to last for a long time, and evolve, ignore proper versioning at your own peril.

2 Likes
17

Successful according to whom? Popularity does not correlate with quality – in my experience they are often at odds with each other. NPM has had security problems several times publicly and who knows how many times without a disclosure. People mostly tolerate NPM, they don’t like it – at least the people I talked with.

But we are venturing in a territory where each of us can require official proof and not get it because it doesn’t exist. And each of us can say the other only has an anecdotal evidence. So the discussion won’t reach any conclusion ever.

So I say let’s draw the line here and give others a chance to chime in.

2 Likes
18

Well said, I agree completely. Thank you for your time.

2 Likes
19

I have a slightly different question. How many of you saw an app using API versioning that actually used the v2 or vn versions? Unfortunately, my experience besides the big API providers is that usually it perpetually stays on v1 and does breaking changes anyway.

6 Likes
20

I go with name spacing the api. It gives the client stability, the provider flexibility to make breaking changes, and provides an upgrade path.