REST api versioning (only version the representation, not the resource itself)

Question

I had a look at Best practices for API versioning?, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am h

Answer 1

For REST, what most answers forget is the data element. I assume multiple version API's still share that same data layer. This means that the data layer forces you to think in a backward compatible way. Big changes that have to be done are only possible if your API changes in a backward compatible way. In practice this means that additional properties are added silently to your entities while using deprecation by date in your API document to indicate when something will be removed. Ideally you use a register scheme with email address of your API key users, so you can notify them about deprecation within a certain scope (a la Facebook).Therefore, I don't think you need to specify a version anywhere.

Answer 2

You could listen for an X-API-Version HTTP request header. If the header exists, then the server must use that version of the API. If the header does not exist, the server may use the latest version of the API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Answer 3

Another approach could be to say that "one representation has multiple APIs":

http://xxx/user/123/api/1.json

And if you wish, you could return the representation using the latest API when requesting like this:

http://xxx/user/123.json

Personally I like other solutions better but this is another approach that I haven't seen suggested here yet.

Answer 4

I completely agree; a URI expresses identity, identity doesn't change when a new version is introduced. There might be new URIs for additional concepts, of course, and existing URIs might redirect … but including a "v2" in the URI smells RPCish to me.

Note that this has got nothing to do with REST, really, as from a REST perspective it's all just characters.

Answer 5

For what it is worth, I agree with you Manuel. You can see my reasoning in this question How to version REST URIs

There are plenty of people that seem to disagree but I would not worry. What your url looks like really does not have a big impact on your client as long as you respect the hypertext constraint.

Answer 6

I find http://xxxx/v1/user/123 confusing as it suggests that there will be a higher api-version someday like http://xxxx/v2/user/123

It doesn't suggest that - however you have that ability in the future.

But this does not make sense in REST terms, the api version itself is HTTP 1.0 or 1.1, which is already sent inside the HTTP request.

The version of YOUR API and the version of HTTP that you are using to make requests do not have to be equal.

One could also argue that such version content-negotiation could be part of the URI inside the path, but I find it counter-intuitive, because you could end-up with different URIs for the same resource and have to maintain redirects at some point.

Its okay to have the version as a URI parameter as you demonstrated.

http://xxx/user/123?v=1 -> for perma-links/hyperlinks