Comments on: Versioning REST Web Services http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ … and there is much to be learned Sun, 18 Jul 2010 13:33:53 +0000 http://wordpress.org/?v=2.9.2 hourly 1 By: Media Types and Plumbing http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-79362 Media Types and Plumbing Tue, 22 Dec 2009 22:10:57 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-79362 <p>[...] a message with no out-of-band-knowledge. Extending this model further, there are attempts to attach version identifiers and schema references to media types. The end goal of these attempts is to let arbitrary clients [...]</p> [...] a message with no out-of-band-knowledge. Extending this model further, there are attempts to attach version identifiers and schema references to media types. The end goal of these attempts is to let arbitrary clients [...]

]]> By: Twitted by dnene http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-76240 Twitted by dnene Thu, 03 Sep 2009 05:31:44 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-76240 <p>[...] This post was Twitted by dnene [...]</p> [...] This post was Twitted by dnene [...]

]]> By: Twitter Trackbacks for Peter Williams - Versioning REST Web Services [barelyenough.org] on Topsy.com http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-76136 Twitter Trackbacks for Peter Williams - Versioning REST Web Services [barelyenough.org] on Topsy.com Fri, 28 Aug 2009 00:27:33 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-76136 <p>[...] Peter Williams - Versioning REST Web Services barelyenough.org/blog/2008/05/versioning-rest-web-services – view page – cached Managing changes to APIs is hard. That is no surprise to anyone who has ever maintained an API of any sort. Web services, being a special case of API, are susceptible to many of the difficulties around versioning as other types of APIs. For HTTP based REST style web services the combination of resources and content negotiation can be used to mitigate most of the issues surrounding API versioning. — From the page [...]</p> [...] Peter Williams – Versioning REST Web Services barelyenough.org/blog/2008/05/versioning-rest-web-services – view page – cached Managing changes to APIs is hard. That is no surprise to anyone who has ever maintained an API of any sort. Web services, being a special case of API, are susceptible to many of the difficulties around versioning as other types of APIs. For HTTP based REST style web services the combination of resources and content negotiation can be used to mitigate most of the issues surrounding API versioning. — From the page [...]

]]> By: Peter Williams http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-76130 Peter Williams Thu, 27 Aug 2009 18:19:52 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-76130 <p>Sajindra,</p> <p>Certainly either approach is workable but they both have downsides.</p> <p>Using a custom version header is effectively not much different from using a custom MIME type. The server will do content negotiation on a non-standard header, which is perfectly legal. The downsides are your application framework probably does not support this out of the box and it is going to be opaque to all the intermediates. However if the server includes the version header in the Varies header everything should work fine.</p> <p>Adding the version identifier in the query string is exactly the same as inserting it somewhere in the path part of the URI. The primary downside of this approach is the pain it causes which upgrading existing clients. You cannot simply update the client to support the next version of the format and assume that all stored URLs are usable. Rather the client will have to support the previous format for all stored URLs and the new format for all new URLs. If the client does not store URLs this issue is, obviously, moot. But in API development you are often not in control of, or even privy to, clients and their development.</p> Sajindra,

Certainly either approach is workable but they both have downsides.

Using a custom version header is effectively not much different from using a custom MIME type. The server will do content negotiation on a non-standard header, which is perfectly legal. The downsides are your application framework probably does not support this out of the box and it is going to be opaque to all the intermediates. However if the server includes the version header in the Varies header everything should work fine.

Adding the version identifier in the query string is exactly the same as inserting it somewhere in the path part of the URI. The primary downside of this approach is the pain it causes which upgrading existing clients. You cannot simply update the client to support the next version of the format and assume that all stored URLs are usable. Rather the client will have to support the previous format for all stored URLs and the new format for all new URLs. If the client does not store URLs this issue is, obviously, moot. But in API development you are often not in control of, or even privy to, clients and their development.

]]> By: Sajindra http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-76126 Sajindra Thu, 27 Aug 2009 11:04:19 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-76126 <p>Hi Peter, Nice Article. i am developing a REST API for my company and coming up with a version management solution is high on the agenda (with few more items).. for the moment I use content negotiation (Accept headers) to defiine the media type the client requets. for e.g. we support the below 1. text/xml 2. application/json 3. application/atom+xml 4. application/rss+xml also we envisage that the consumer of these services can be any device (just not a browser).. can be a Google MAP, rss or atom reader or even a hand held devise. so in addition to using headers we used . extensions also. e.g. ...faults.xml, faults.rss likewise.</p> <p>So if we use a vendor MILE media type, we would have to extend the above to some thing like below: 1. text/v2-xml 2. application/v2-json 3. application/atom-v2+xml 4. application/rss-v2+xml ? Also I have seen that Google Data API uses two mechanism 1) version header 2) a query param based method (nor a /v2 type that would break a resource hierarchy ) - i.e. xyz.com/faults/423434?v=2</p> <p>in order to support most of the devises (that can process headers or simple devises) what is your advise pls?</p> Hi Peter,
Nice Article. i am developing a REST API for my company and coming up with a version management solution is high on the agenda (with few more items)..
for the moment I use content negotiation (Accept headers) to defiine the media type the client requets. for e.g. we support the below
1. text/xml
2. application/json
3. application/atom+xml
4. application/rss+xml
also we envisage that the consumer of these services can be any device (just not a browser).. can be a Google MAP, rss or atom reader or even a hand held devise. so in addition to using headers we used . extensions also. e.g. …faults.xml, faults.rss likewise.

So if we use a vendor MILE media type, we would have to extend the above to some thing like below:
1. text/v2-xml
2. application/v2-json
3. application/atom-v2+xml
4. application/rss-v2+xml
?
Also I have seen that Google Data API uses two mechanism
1) version header
2) a query param based method (nor a /v2 type that would break a resource hierarchy ) – i.e. xyz.com/faults/423434?v=2

in order to support most of the devises (that can process headers or simple devises) what is your advise pls?

]]> By: Peter Williams http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-74886 Peter Williams Mon, 20 Jul 2009 18:09:15 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-74886 <p>Colin Jack, It works very well for facilitating incomparable changes to an API. However, each such incompatible change adds long term maintenance burdens to the server implementation. Before making any incompatible change to an API the benefits of the change should be weighed against the cost of maintaining that change.</p> <p>The approach described here results in a very low burden on the client side combined less of a burden on the service side than most versioning approaches, but it is not free. It is usually better for everyone to avoid introducing incompatible changes whenever possible.</p> Colin Jack, It works very well for facilitating incomparable changes to an API. However, each such incompatible change adds long term maintenance burdens to the server implementation. Before making any incompatible change to an API the benefits of the change should be weighed against the cost of maintaining that change.

The approach described here results in a very low burden on the client side combined less of a burden on the service side than most versioning approaches, but it is not free. It is usually better for everyone to avoid introducing incompatible changes whenever possible.

]]> By: Colin Jack http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-74875 Colin Jack Mon, 20 Jul 2009 10:11:21 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-74875 <p>I'm interested in how this works in practice, in particular any breaking change to any contract related to "application/vnd.mycompany.myapp" is going to cause us to release a new version and I'm wondering whether this results in a lot of new versions?</p> I’m interested in how this works in practice, in particular any breaking change to any contract related to “application/vnd.mycompany.myapp” is going to cause us to release a new version and I’m wondering whether this results in a lot of new versions?

]]> By: The Amazing Blog : Your Web Service Might Not Be RESTful If… http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-74870 The Amazing Blog : Your Web Service Might Not Be RESTful If… Mon, 20 Jul 2009 04:44:47 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-74870 <p>[...] just brushed the surface of this topic. For more, Peter Williams has an excellent discussion of it here, here, and here. (disclaimer &emdash; Peter is a former coworker and personal friend. This section [...]</p> [...] just brushed the surface of this topic. For more, Peter Williams has an excellent discussion of it here, here, and here. (disclaimer &emdash; Peter is a former coworker and personal friend. This section [...]

]]> By: andy.edmonds.be › links for 2009-07-08 http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-74603 andy.edmonds.be › links for 2009-07-08 Thu, 09 Jul 2009 00:37:04 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-74603 <p>[...] Peter Williams - Versioning REST Web Services (tags: rest versioning api) This was written by andy. Posted on Thursday, July 9, 2009, at 1:36 am. Filed under Uncategorized. Bookmark the permalink. Follow comments here with the RSS feed. Post a comment or leave a trackback. [...]</p> [...] Peter Williams – Versioning REST Web Services (tags: rest versioning api) This was written by andy. Posted on Thursday, July 9, 2009, at 1:36 am. Filed under Uncategorized. Bookmark the permalink. Follow comments here with the RSS feed. Post a comment or leave a trackback. [...]

]]> By: Mark Waddle http://barelyenough.org/blog/2008/05/versioning-rest-web-services/comment-page-1/#comment-72397 Mark Waddle Tue, 05 May 2009 01:27:35 +0000 http://pezra.barelyenough.org/blog/?p=335#comment-72397 <p>Hello Peter,</p> <p>This is an interesting idea. I mostly like the concept, except that I don't find it to be at all discoverable. Is there an HTTP request I can make that will tell me what content-types a resource supports? I looked up HEAD and it doesn't seem to do that. Your recommendation also conflicts with this http://www.w3.org/2001/tag/doc/alternatives-discovery.html, which seems as well reasoned out as your argument, but with improved discoverability.</p> <p>Mark</p> Hello Peter,

This is an interesting idea. I mostly like the concept, except that I don’t find it to be at all discoverable. Is there an HTTP request I can make that will tell me what content-types a resource supports? I looked up HEAD and it doesn’t seem to do that.
Your recommendation also conflicts with this http://www.w3.org/2001/tag/doc/alternatives-discovery.html, which seems as well reasoned out as your argument, but with improved discoverability.

Mark

]]>