Versioning Strategies For RESTful Services

Posted by Dilip Krishnan on Mar 04, 2010

Sections

Architecture & Design,

Enterprise Architecture,

Operations & Infrastructure

Topics

SOA ,

REST ,

Versioning

Tags

Media Types ,

URI

In his article, Stu Charlton summarizes the various options available for versioning RESTful services which he prefaces by saying “These can be tricky concepts to describe, and I don't really want to write a small book on this topic”. He categorizes the versioning problem into two types; Data Versioning, which aims to version the resource itself so tracking changes to state of any given resource becomes possible; and Language Versioning which refers to the protocol itself; in other words the representation.

URI versioning […] is a design choice when resources are immutable across time and we create new resources for state changes (similar to how we manage time-series data in a database).

Language extension or versioning, on the other hand, the state is unchanged, but the way that data is represented has changed.

Stu defers to W3C TAG's draft document by David Orchard on versioning compatibility strategies which elucidates the intricacies of backwards, forwards and incompatible changes. “Language extension requires thought”  he says, and emphasizes that

Rule #1: Prefer to extend a language in a forwards and/or backwards compatible manner. Version indicators are a last resort, to denote incompatible changes.

He summarizes the document in tabular form as follows.

	Consumer	Producer
Backwards-Compatible	Lookup version notifications	Replacement or Side-by-side Version notification via out-of-band channel or links
Forwards-Compatible	Must accept unknowns Must preserve unknowns if persisting state Version identifier substitution model	Media type specification clearly defines consumer forward compatibility expectations (and/or uses a machine-readable schema to denote forward-compatibility extension areas)
Incompatible	Check for version identifier	Side-by-side or Breaking Replacement

He goes on to define some of the terms used in the table such as version notifications, replacement, side-by-side, version identifiers and how producers and consumers deal with unknown elements in the “language” in different compatibility scenarios. He examines various strategies for providing version identifiers and discusses his preference on the priority with which that these strategies be applied.

Version identifier inside the media type content

This has many examples in the wild, such as HTML DOCTYPE, some uses of XMLNS, a version identifier inside your PDF document. […] It's the way that most web media types have long worked, with varying degrees of success, but note that those formats were long designed with forward compatibility in mind.

Version identifier in the MIME type

[…] The benefit here is that this enables side-by-side versioning without impacting the URI-space. [….but…] this reeks of avoiding hypermedia and trying to push things to the other layers of the Web Architecture (HTTP and/or URIs). e.g. application/vnd.mytype;version=2

Version identifier in the URI

It's clear we mint URIs when the semantics of the resource itself changes. So, if they change with the language, then mint new URIs […] e.g. http://example.com/data/v1/po/123

The other problem is bookmarks, which in a data system are actually known as "foreign keys". Anyone with a relational data background knows that their primary keys really shouldn't change, as it's expensive to propagate that change to foreign keys.

He recommends reading Chapter 13 of the book RESTful Web Services Cookbook by Subbu Allamaraju to learn more on the subject and concludes his article with the following summary

1. Prefer extensible, forwards & backwards compatible languages and the replacement approach to compatibility. Note the W3C TAG's position on version identifiers
2. Be judicious when you use version identifiers in URIs, as cool URIs don't change
3. For side-by-side deployments, always include a section in your media, or link relation(s), to point to new/old versions, and update references lazily as the consumer refreshes its cached value. Use permanent redirects to retire URIs bound to old language versions.
4. Version URIs if the semantics of the resource changed, but be courteous to consumers by ensuring links are available to denote the old vs. new

Stu's article tries to brings together the elements that make up the solution space for the versioning RESTful services, however these strategies continue to be fraught with debate on what the right options are. 

1. Back to top

   Clarification request

   by Andrew Marshall

   Could you clarify or expand on the statement "Version identifier inside the media type content"? I think an example is all I really need.
   
   Thanks! :-)

   Reply

2. Back to top

   Re: Clarification request

   by Dilip Krishnan

   An example of that would differ based on media type... but lets say you are using the xml dialect; consider a media type content for a PO message
   
   

   
   ...
   <purchaseOrder xmlns="urn:someuri:version:1" >
      <shipTo country="US">...</shipTo>
      <items>...</items>
   </purchaseOrder>
   

   
   
   In this example we embed the versioning of the content via the xml namespace.

   Reply

3. Back to top

   Re: Clarification request

   by Andrew Marshall

   That's what I was hoping for. Many thanks! :-)

   Reply

• Older >