BT
x Your opinion matters! Please fill in the InfoQ Survey about your reading habits!

Versioning Strategies For RESTful Services

by Dilip Krishnan on Mar 04, 2010 |

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

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

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! :-)

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.

Re: Clarification request by Andrew Marshall

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

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT