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 |
|
|
| Forwards-Compatible |
|
|
| Incompatible |
|
|
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
- Prefer extensible, forwards & backwards compatible languages and the replacement approach to compatibility. Note the W3C TAG's position on version identifiers
- Be judicious when you use version identifiers in URIs, as cool URIs don't change
- 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.
- 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.
