7 ms·

Version your RESTful API responses

26 points by yuxt 14y ago

bluetidepro 14y ago
I like this idea a lot! I'm curious if anyone else finds major flaws in this idea but it seems to make a lot of sense to me. Yes, it may change slightly how you do your calls, but if the logic works and that's the "worse thing" that could come from this then I think it's worth implementing.
- ldh 14y ago
  One of the main drawbacks to the HTTP Accept header approach for both versioning and content negotiation is that it makes it less convenient to test from a browser when you can't encode those things in the URL. Personally I feel that using the header feels more "right" and lines up with the available mechanisms of HTTP. I think the inconvenience could be easily overcome with browser plugins, for example.
  - DropkickM16 14y ago
    You can always add a version=v1 to the query parameters and use that as an override when performing content negotiation. It's still not terribly convenient.
- stuff4ben 14y ago
  Some libraries that are used to connect to versioned resources like this don't support these types of media types. I tried to version my RESTful APIs exactly like this and ran into integration problems with an externally developed client which was based in Flex. It could have been our contractors not knowing Flex all that well or it could have been inflexibility in the language libraries itself (pun intended).
- iSnow 14y ago
  Seems to me he is abusing the Accept-header. In his example, the application provides a JSON-response, but with a vendor-specific media type. Once the API version changes, he changes the media type again. This is both impractical because if the client application consuming the content happens to be a web browser, it will not see JSON and at least to me seems like a major flaw: if it is JSON, use the appropriate media type. If you need to fiddle with HTTP headers, probably a X-API-VERSION header would be more logical instead of clobbering the media type.
  - urbanautomaton 14y ago
    I don't think "media type" is synonymous with "data format". For example, IANA considers atomcat+xml and atomsvc+xml to be distinct media types [1], despite them both being XML, and there are 406 other XML-based media types in that list. [1] http://www.iana.org/assignments/media-types/application/index.html http://www.iana.org/assignments/media-types/application/inde...
- awj 14y ago
  * You cannot test this from the browser. * Many, many client developers will be confused by this approach. Also if they're using a shitty http library (often, yes) they'll hate you. * What happens when someone sends an "Accept: application/json"? If you default to "send the latest" developers will fail to read your docs and get pissed when your next version breaks their code. * His citation of Fielding's dissertation at best fails to support his claim and at worst is a misunderstanding of it. How is "put this in your accept header" any more of a uniform interface than "this thing goes in urls"? If you're doing HATEOAS[1] properly the answer is: "accept headers are less general and thus worse". If you include api versions as a fundamental part of the notion of a resource they seem to become important enough to need top level (e.g. URI) support. All in all this seems like a thinly veiled argument for URI purity for its own sake. API versions change the definitions of what a resource looks like and what you can do with it. What more is there to a resource? What benefits, aside from sweeping the versioning mess under the header rug, does this provide? [1] http://en.wikipedia.org/wiki/HATEOAS http://en.wikipedia.org/wiki/HATEOAS
  - regularfry 14y ago
    URIs should be black boxes. My understanding is that the client should need no understanding at all of their content.
    - awj 14y ago
      I agree. This is only possible when all resource access flows from a predefined "root" resource via hyperlinks. If you're doing that, why force (arguably more difficult) accept header handling on your api clients? Then they have to set the accept header correctly at every request instead of getting the version number right once when retrieving the root document. Beyond that debugging now requires access to / a record of the accept headers involved, and returning the latest version for plain application/json creates a very nasty bug for clients. I don't think REST meaningfully comes down on either side of this idea. I do think practicality sits highly in favor of versions in URIs.
      - ldh 14y ago
terryjsmith 14y ago
While this seems like a good solution, I'm not sure the problem is real: to me, a v1 API and a v2 API are two separate APIs, so the URLs for that API aren't really changing during it's lifetime (ie. the v1 stuff will stay the same for those continuing to use it). I think this is just a mis-interpretation of a core REST/web principle that the URIs for a specific resource in the API shouldn't change (hence creating a v2 or other sub-directory if you're going to change the output or functionality).
- ldh 14y ago
  Sure, if your URIs are versioned those are by definition not going to change. However, I would stress that the 'R' in URI stands for "Resource", not "particular version of an API to request that resource". It seems like your approach places the implementation details of requesting a resource over the actual identifier for that resource.
  - bonzoesc 14y ago
    It's useful semantically to think of different versions of a resource as different resources. It makes reasoning about them free of any assumptions the previous versions may have introduced.
    - ldh 14y ago
      I'm not dismissing the idea that resources need to be versioned, certainly a client written against v1 might not be able to handle the v2 representation of the resource. It's just that I think the abstraction the resource is representing generally doesn't change just because the implementation details behind it have. If you change the way a "customerId" is formatted in V2, the idea of providing a "customer" resource hasn't changed, and as a matter of style I think it's cleaner that the URL for the customer record representing a single person doesn't change or suddenly split into multiple resources which really represent one entity. IMO the header-versioned approach expresses the semantic difference you point out cleanly, and in addition does not come with undesirable side-effect of diluting the URI concept.
candybar 14y ago
I don't hate the idea or anything but I don't see what problem this solves in practice?
- 13rules 14y ago
  Agree ... normally the V2 API comes out with major revisions, such that it would not work with someone that coded up an app based on the V1 API. Using /v1/ and /v2/ allows customers to transition over some set amount of time. There is some value in keeping things simple for your end-users.
  - ajanuary 14y ago
    If the customers use 'Accept: application/vnd.example.v1+json' and 'Accept: application/vnd.example.v2+json' they can also transition over in the same manner.
- optymizer 14y ago
  It solves the problem of client-server communication. This is the same idea as with: "GET /car HTTP/1.0" and "GET /car HTTP/1.1" . It provides a clear way to specify which protocol the client speaks, while allowing the URI to stay the same. Contrast this with: "GET /v1/car" and "GET /v2/car". The article simply uses the Accept: header to achieve the same.
  - candybar 14y ago
    But how is this better in practice? Why is it important that the URI stay the same? I don't see why coding the version information in the header is better than coding it in the URI. The latter seems much easier to manage in practice.
    - ldh 14y ago
      In this example, the client knows what version it can handle and should specify that separately than the user providing the URI for the desired resource. Separation of concerns. Why make the end user guess about version numbers?
bryanh 14y ago
The whole point of a REST API version bump is that it is an artifact of introducing necessary breaking changes (either removing an endpoint at X path, removing Y keys, or even serializing dates in Z format). Though there have been many detractors, I still think URL based versioning is the best way to go. How do you version a header on a resource that goes away or pops into existence? What if I just ask for "application/json" or the "freshest" due to ignorance and you move the target and get even fresher? There is very little practical benefit to versioning in a HTTP header except some argument about URI purity.
- ldh 14y ago
  If you're writing a client which is sensitive to the resource representation changing over time and you're using something that calls itself an API, hopefully one would skim the provided docs enough to see that you might want to explicitly state the version you want. Or notice that the Content-Type returned for the generic application/json query is a versioned type. I acknowledge that it's a little more work than just banging out a versioned URI, but it's not that much work and I like the URI/conceptual purity.
  - zimbatm 14y ago
    > and I like the URI/conceptual purity. This sums up pretty much the whole debate. Pragmatics vs idealists.
    - j_s 14y ago
      The interesting thing is that it is a false dichotomy - it's easy enough to implement both. Perhaps enhanced by adding a flag on the documentation to flip between pragmatist/idealist so each only sees their one way to do it right...
  - Osiris 14y ago
    Another solution that I've seen is to use a custom header in the request such as X-Api-Client-Version: 1 If the header isn't provided, then the most current version of the API is called. The nice thing about this is that it doesn't 'pollute' the URI and it allows for automatic upgrading to the latest version of the API if the developer doesn't specify the API version.
zimbatm 14y ago
How often do you update the major version of your API ? Most of the time you can just augment your API with new end-points and keep the old paths around for backward-compatibility. When you're ready to change the major version you might as well start a new service from scratch with everything that you have learned. Now that all your responses have a non IANA-approved[1] content-type, standard clients won't see it as JSON by default. Your curl requests are longer to type because you have to add this '-HAccept:application/vnd.something+json' string to your them. The reality is that bad developers will have broken clients when you update your API in any case. I'm grateful that the REST movement brought attention to follow the HTTP protocol more closely but in practice, nobody writes truly RESTful clients. For that you would need to write a client that follows URLs passed in the body or in the headers. For example if you implement pagination, you're supposed to fetch page 1 and then follow the links until you're at the page you want. In reality you just make a page= attribute convention that avoids all these unnecessary round-trips. [1]: http://www.iana.org/assignments/media-types/index.html http://www.iana.org/assignments/media-types/index.html
urbanautomaton 14y ago
I personally prefer this approach - certainly if the changes you're making are only to the representation of your resources, then (assuming they can't be made purely additively, i.e. without breaking existing clients) simply making a new content type available seems the natural way to go. If it's of interest, I wrote a couple of articles about how we implemented exactly this sort of versioning in Rails for our app's API: http://techblog.tribesports.com/blog/2011/09/24/versioning-the-tribesports-api http://techblog.tribesports.com/blog/2011/09/24/versioning-t... http://techblog.tribesports.com/blog/2011/09/24/separating-api-logic-with-decorators http://techblog.tribesports.com/blog/2011/09/24/separating-a... I think these demonstrate the advantages of content negotiation as a versioning mechanism. To introduce a new API representation, we simply have to define a new set of decorators for our exposed resources, define a new MIME type and we're set. No monkeying with our routing, no messing around in controllers; a view-level change entails only view-level code alterations.
pbreit 14y ago
With just a bit of forethought and a little planning, an API almost never really needs to be versioned in either way. One of the problems with versioning is that it almost encourages changing the API and most consumers are slow to update, if at all.

26 points by yuxt 14y ago

I like this idea a lot! I'm curious if anyone else finds major flaws in this idea but it seems to make a lot of sense to me. Yes, it may change slightly how you do your calls, but if the logic works and that's the "worse thing" that could come from this then I think it's worth implementing.

ldh 14y ago
One of the main drawbacks to the HTTP Accept header approach for both versioning and content negotiation is that it makes it less convenient to test from a browser when you can't encode those things in the URL. Personally I feel that using the header feels more "right" and lines up with the available mechanisms of HTTP. I think the inconvenience could be easily overcome with browser plugins, for example.
- DropkickM16 14y ago
  You can always add a version=v1 to the query parameters and use that as an override when performing content negotiation. It's still not terribly convenient.
stuff4ben 14y ago
Some libraries that are used to connect to versioned resources like this don't support these types of media types. I tried to version my RESTful APIs exactly like this and ran into integration problems with an externally developed client which was based in Flex. It could have been our contractors not knowing Flex all that well or it could have been inflexibility in the language libraries itself (pun intended).
iSnow 14y ago
Seems to me he is abusing the Accept-header. In his example, the application provides a JSON-response, but with a vendor-specific media type. Once the API version changes, he changes the media type again. This is both impractical because if the client application consuming the content happens to be a web browser, it will not see JSON and at least to me seems like a major flaw: if it is JSON, use the appropriate media type. If you need to fiddle with HTTP headers, probably a X-API-VERSION header would be more logical instead of clobbering the media type.
- urbanautomaton 14y ago
  I don't think "media type" is synonymous with "data format". For example, IANA considers atomcat+xml and atomsvc+xml to be distinct media types [1], despite them both being XML, and there are 406 other XML-based media types in that list. [1] http://www.iana.org/assignments/media-types/application/index.html http://www.iana.org/assignments/media-types/application/inde...
awj 14y ago
* You cannot test this from the browser. * Many, many client developers will be confused by this approach. Also if they're using a shitty http library (often, yes) they'll hate you. * What happens when someone sends an "Accept: application/json"? If you default to "send the latest" developers will fail to read your docs and get pissed when your next version breaks their code. * His citation of Fielding's dissertation at best fails to support his claim and at worst is a misunderstanding of it. How is "put this in your accept header" any more of a uniform interface than "this thing goes in urls"? If you're doing HATEOAS[1] properly the answer is: "accept headers are less general and thus worse". If you include api versions as a fundamental part of the notion of a resource they seem to become important enough to need top level (e.g. URI) support. All in all this seems like a thinly veiled argument for URI purity for its own sake. API versions change the definitions of what a resource looks like and what you can do with it. What more is there to a resource? What benefits, aside from sweeping the versioning mess under the header rug, does this provide? [1] http://en.wikipedia.org/wiki/HATEOAS http://en.wikipedia.org/wiki/HATEOAS
- regularfry 14y ago
  URIs should be black boxes. My understanding is that the client should need no understanding at all of their content.
  - awj 14y ago
    I agree. This is only possible when all resource access flows from a predefined "root" resource via hyperlinks. If you're doing that, why force (arguably more difficult) accept header handling on your api clients? Then they have to set the accept header correctly at every request instead of getting the version number right once when retrieving the root document. Beyond that debugging now requires access to / a record of the accept headers involved, and returning the latest version for plain application/json creates a very nasty bug for clients. I don't think REST meaningfully comes down on either side of this idea. I do think practicality sits highly in favor of versions in URIs.
    - ldh 14y ago

terryjsmith 14y ago

While this seems like a good solution, I'm not sure the problem is real: to me, a v1 API and a v2 API are two separate APIs, so the URLs for that API aren't really changing during it's lifetime (ie. the v1 stuff will stay the same for those continuing to use it). I think this is just a mis-interpretation of a core REST/web principle that the URIs for a specific resource in the API shouldn't change (hence creating a v2 or other sub-directory if you're going to change the output or functionality).

ldh 14y ago
Sure, if your URIs are versioned those are by definition not going to change. However, I would stress that the 'R' in URI stands for "Resource", not "particular version of an API to request that resource". It seems like your approach places the implementation details of requesting a resource over the actual identifier for that resource.
- bonzoesc 14y ago
  It's useful semantically to think of different versions of a resource as different resources. It makes reasoning about them free of any assumptions the previous versions may have introduced.
  - ldh 14y ago
    I'm not dismissing the idea that resources need to be versioned, certainly a client written against v1 might not be able to handle the v2 representation of the resource. It's just that I think the abstraction the resource is representing generally doesn't change just because the implementation details behind it have. If you change the way a "customerId" is formatted in V2, the idea of providing a "customer" resource hasn't changed, and as a matter of style I think it's cleaner that the URL for the customer record representing a single person doesn't change or suddenly split into multiple resources which really represent one entity. IMO the header-versioned approach expresses the semantic difference you point out cleanly, and in addition does not come with undesirable side-effect of diluting the URI concept.

candybar 14y ago

I don't hate the idea or anything but I don't see what problem this solves in practice?

13rules 14y ago
Agree ... normally the V2 API comes out with major revisions, such that it would not work with someone that coded up an app based on the V1 API. Using /v1/ and /v2/ allows customers to transition over some set amount of time. There is some value in keeping things simple for your end-users.
- ajanuary 14y ago
  If the customers use 'Accept: application/vnd.example.v1+json' and 'Accept: application/vnd.example.v2+json' they can also transition over in the same manner.
optymizer 14y ago
It solves the problem of client-server communication. This is the same idea as with: "GET /car HTTP/1.0" and "GET /car HTTP/1.1" . It provides a clear way to specify which protocol the client speaks, while allowing the URI to stay the same. Contrast this with: "GET /v1/car" and "GET /v2/car". The article simply uses the Accept: header to achieve the same.
- candybar 14y ago
  But how is this better in practice? Why is it important that the URI stay the same? I don't see why coding the version information in the header is better than coding it in the URI. The latter seems much easier to manage in practice.
  - ldh 14y ago
    In this example, the client knows what version it can handle and should specify that separately than the user providing the URI for the desired resource. Separation of concerns. Why make the end user guess about version numbers?

bryanh 14y ago

The whole point of a REST API version bump is that it is an artifact of introducing necessary breaking changes (either removing an endpoint at X path, removing Y keys, or even serializing dates in Z format). Though there have been many detractors, I still think URL based versioning is the best way to go. How do you version a header on a resource that goes away or pops into existence? What if I just ask for "application/json" or the "freshest" due to ignorance and you move the target and get even fresher? There is very little practical benefit to versioning in a HTTP header except some argument about URI purity.

ldh 14y ago
If you're writing a client which is sensitive to the resource representation changing over time and you're using something that calls itself an API, hopefully one would skim the provided docs enough to see that you might want to explicitly state the version you want. Or notice that the Content-Type returned for the generic application/json query is a versioned type. I acknowledge that it's a little more work than just banging out a versioned URI, but it's not that much work and I like the URI/conceptual purity.
- zimbatm 14y ago
  > and I like the URI/conceptual purity. This sums up pretty much the whole debate. Pragmatics vs idealists.
  - j_s 14y ago
    The interesting thing is that it is a false dichotomy - it's easy enough to implement both. Perhaps enhanced by adding a flag on the documentation to flip between pragmatist/idealist so each only sees their one way to do it right...
- Osiris 14y ago
  Another solution that I've seen is to use a custom header in the request such as X-Api-Client-Version: 1 If the header isn't provided, then the most current version of the API is called. The nice thing about this is that it doesn't 'pollute' the URI and it allows for automatic upgrading to the latest version of the API if the developer doesn't specify the API version.

zimbatm 14y ago

How often do you update the major version of your API ? Most of the time you can just augment your API with new end-points and keep the old paths around for backward-compatibility. When you're ready to change the major version you might as well start a new service from scratch with everything that you have learned. Now that all your responses have a non IANA-approved[1] content-type, standard clients won't see it as JSON by default. Your curl requests are longer to type because you have to add this '-HAccept:application/vnd.something+json' string to your them. The reality is that bad developers will have broken clients when you update your API in any case. I'm grateful that the REST movement brought attention to follow the HTTP protocol more closely but in practice, nobody writes truly RESTful clients. For that you would need to write a client that follows URLs passed in the body or in the headers. For example if you implement pagination, you're supposed to fetch page 1 and then follow the links until you're at the page you want. In reality you just make a page= attribute convention that avoids all these unnecessary round-trips. [1]: http://www.iana.org/assignments/media-types/index.html http://www.iana.org/assignments/media-types/index.html

urbanautomaton 14y ago

I personally prefer this approach - certainly if the changes you're making are only to the representation of your resources, then (assuming they can't be made purely additively, i.e. without breaking existing clients) simply making a new content type available seems the natural way to go. If it's of interest, I wrote a couple of articles about how we implemented exactly this sort of versioning in Rails for our app's API: http://techblog.tribesports.com/blog/2011/09/24/versioning-the-tribesports-api http://techblog.tribesports.com/blog/2011/09/24/versioning-t... http://techblog.tribesports.com/blog/2011/09/24/separating-api-logic-with-decorators http://techblog.tribesports.com/blog/2011/09/24/separating-a... I think these demonstrate the advantages of content negotiation as a versioning mechanism. To introduce a new API representation, we simply have to define a new set of decorators for our exposed resources, define a new MIME type and we're set. No monkeying with our routing, no messing around in controllers; a view-level change entails only view-level code alterations.

pbreit 14y ago

With just a bit of forethought and a little planning, an API almost never really needs to be versioned in either way. One of the problems with versioning is that it almost encourages changing the API and most consumers are slow to update, if at all.