Comments on: Versioning REST Web Services

By: Jason Heiss

Jason Heiss — Thu, 02 Feb 2012 14:46:19 +0000

Peter,
In your comments both here and on the “response to Jean” post you indicate that you don’t think an accept-extension like “level” or “version” is appropriate for indicating incompatible (i.e. major version) changes. However my reading of the examples in the HTTP spec and related historical documents leads me to believe that was exactly the intended purpose. All usage of the “level” extension historically seems to have been in relation to the “text/html” MIME type, and specifically to indicate major versions of the HTML spec (HTML 2, HTML 3, etc.) This page (http://www.w3.org/MarkUp/table-deployment) dated 1995 clearly shows usage of a “text/html; level=3″ media type to indicate to HTML 2 only clients that they won’t understand the markup and should not attempt to do so.

That said, this is largely an academic exercise. In the absence of specific definition it seems like media types must be treated as opaque strings, so “application/vnd.mycompany.myapp-v2+xml” and “application/vnd.mycompany.myapp+xml; level=2″ both serve the same purpose. Since there seems to be consensus that the former is the better format to use I’ll be going that way, I just don’t see any reason that the later format is any less valid. And in fact using the “level” extension for minor versioning seems counter to historical precedent, but (IMHO) acceptable and harmless if used on a custom MIME time.

By: Peter Williams

Peter Williams — Tue, 27 Dec 2011 16:46:15 +0000

Michael,
It absolutely applies to the content type of POST and PUT requests. Just as the accept header field of GET requests allows the server to give the client the particular representation it requires, the content-type header field of POST and PUT requests gives the server the information it needs to correctly interpret the data set by the client.

By: Michael

Michael — Fri, 23 Dec 2011 02:08:13 +0000

You talk about using the ACCEPT header – does the same apply to the Content-type of a POST/PUT? Tha API consists of both input AND output.

By: Peter Williams

Peter Williams — Thu, 08 Dec 2011 15:36:00 +0000

The important characteristic of PUTs is that they must be idempotent, not that they do not allow partial updates. It is very common for the body of PUT request to not include every property of the resource. For example, last updated timestamp fields.

I this case the put would be idempotent. The older client neither knows nor cares about this new property and so it does not really care how it’s values are handled. Either of the ways you mentioned to handle the missing property value would be ok.

Caches will take care of themselves. Caches don’t use the body of the PUT. They merely invalidate the previously cached representations for that resource. That means the next GET request for that resource will go to the server and it’s response will be cached. Assuming the new property is always returned the caches will keep up to date.

By: Jim Purbrick

Jim Purbrick — Thu, 08 Dec 2011 14:34:54 +0000

How does this work with read/write APIs? If I add an attribute as a non-breaking change and so don’t change the media type, old clients will continue to PUT and POST data missing the new attribute. I can fix this on the server by setting the attribute to a default value, or leaving the current value of the attribute unchanged, but does it cause problems with caches, which may replace their cached version with the partial update? Isn’t this effectively the same problem as doing partial updates with PUT?

By: Link dump for August 31st | The Queue Incorporated

Link dump for August 31st | The Queue Incorporated — Thu, 01 Sep 2011 04:03:15 +0000

[...] Peter Williams – Versioning REST Web Services – an old article but a nice alternative for handling API versioning [...]

By: links for 2011-07-11 « Blarney Fellow

links for 2011-07-11 « Blarney Fellow — Tue, 12 Jul 2011 00:10:33 +0000

[...] Peter Williams – Versioning REST Web Services (tags: rest api http) [...]

By: A few great things to read on REST (technical) | jemery.com

A few great things to read on REST (technical) | jemery.com — Tue, 28 Jun 2011 21:21:17 +0000

[...] VERSIONING REST WEB SERVICES [...]

By: Using Mementos for Rest Data « My Weblog

Using Mementos for Rest Data « My Weblog — Wed, 23 Mar 2011 23:27:32 +0000

[...] impact of this versioning of the data. There are some discussions about this by Peter Williams, Versioning Rest Web Services, and Ganesh Prasad asks, Does Rest Need [...]

By: Quora

Quora — Fri, 18 Mar 2011 13:00:33 +0000

Should a RESTful web service API be versioned?…

No, I do not believe it is necessary to “version” a REST api. It is certainly possible to build RESTful apis and manage breaking changes without ever including version numbers in the URI. By far the most important thing to ensure is that clients a…