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

Question

Have I looked at API versioning guidelines? , but I'm not quite sure about the answer, so again I wonder about the version with a more specific example. I have two URIs (one with version as part of the URI and one without):

http://xxxx/v1/user/123 -> favored solution in discussed thread http://xxxx/user/123 

I have doubts that the first link expresses the idea of ​​REST. I find http://xxxx/v1/user/123 confusing, as it suggests that someday there will be a higher version of the api, like http://xxxx/v2/user/123 . But this does not make sense in terms of REST, the api version itself is HTTP 1.0 or 1.1, which is already sent inside the HTTP request. This resource-oriented REST resource is very different from other api interfaces such as SOAP or Java interfaces (where they usually have api versions in qualified names).

In REST, the only thing that makes sense in the version is the representation of this resource (for example, new fields are added or deleted). This versioning refers to the content negotiation part, for example:

 http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header http://xxx/user/123?v=1 -> for perma-links/hyperlinks 

It can also be argued that such reconciling version content may be part of the URI inside the path, but I find it intuitive because you could get different URIs for the same resource and must support redirects to some point.

To summarize: there are no api versions in the REST URI, only a version of the resource representation. The presented version information refers to content negotiation (as a Param or HTTP "Accept" request).

What do you think? What things do you disagree / agree on?

Answer 1

I totally agree; URI expresses identity; identity does not change when a new version is introduced. Of course, there may be new URIs for additional concepts, and existing URIs may be redirected ... but including "v2" in the URI, RPCish smells to me.

Please note that this has nothing to do with REST, indeed, since from a REST point of view, these are all just characters.

Answer 2

You can listen to the header of the X-API-Version HTTP request. If the header exists, the server should use this version of the API. If the header does not exist, the server can 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

For what it's worth, I agree with you Manuel. You can see my reasoning in this question. How to change the REST URI

There are many people who do not seem to agree, but I would not worry. The way your URL looks does not really have much impact on your client if you respect the hypertext constraint.

Answer 4

I agree that you do not want to see the versions in the URI of the resources represented in your API. This makes them not "cool." Also agree that these are the most likely changes.

However, it raises the question of what happens when you change the content of a particular view. For example, if your original JSON representation of frobnitz is

 {"x": "bam", "y": "hello"} 

and you want to add the "z" field, you can feel that the client should have some idea that we are currently on version 2 of some data scheme.

I am not sure about that. I think you have several options:

• Make your customers flexible in the face by slightly changing their presentation. In the above example, we are still creating a JSON dictionary.
• If necessary, put the version in the view itself (the version field in this example). That way, you are actually declaring a subview in content of type JSON. I find this to be quite limited.
• Use your own MIME types and their version: application / x-my-special-json1.0, application / x-my-special-json1.1. This allows you to change your ideas independently. Again, with this you are making a significant demand for your customers to know what is happening.

In general, I think you want to optimize your API and your views for clients that you yourself did not invent; that other people will create when they discover your resources. I believe this is useful even if you are doing something private, because it creates a useful design constraint that will help make your system more reliable.

Answer 5

I find http: // xxxx / v1 / user / 123 confused, because it says that there will someday be higher api version for example http: // xxxx / v2 / user / 123

This does not suggest that - however, you have this 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 use to execute requests should not be equal.

You could also argue that such a version of Content Consolidation may be part of the URI inside the path, but I find it counterintuitive because you could end up with different URIs for the same resource and must support redirects at some point.

It’s good that the version is a URI parameter, as you showed.

http: // xxx / user / 123? v = 1 → for perm links / hyperlinks

Answer 6

Another approach might be to say that "one view has multiple APIs":

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

And if you want, you can return the view using the latest API when requested:

 http://xxx/user/123.json 

Personally, I better like other solutions, but this is another approach that I have not seen here.

Answer 7

For REST, what most of the answers forget, is a data item. I assume that several versions of the API are still using the same data layer. This means that the data layer makes you think the other way around. The big changes that need to be made are only possible if your API changes backwards in a compatible way. In practice, this means that additional properties are added silently to your entities, while using expiration by date in your API document indicates when something will be deleted. Ideally, you use a registration scheme with the email address of your API key users, so you can notify them of a failure in a specific area (a la Facebook). Therefore, I do not think you need to specify the version anywhere.