Versioning REST

One thing I dislike about URL schemes for versioning a web services resource is it feels decidedly un-RESTful. The URL of a resource shouldn’t change simply because the format of that resource’s representation does.

By placing version information in the URL and simply adding that to the documentation, clients are not able to find old versions or even be updated when there is a new version. Version information should be located in the document, and clients should be able to tell which version they are using and if it is the latest version.

A nagging concern I had for versioned URLs is that small, backward-compatible changes or new features won’t be available to the client because they’re using /v2/yourapi but the new features are only in /v3/yourapi. If I add new data or enrich the existing data, I want all clients to have access to it immediately.

To avoid client synchronization problems the server always allows clients to access old representations of a resource and gives these clients an easy way to locate both the old and new representations.

In Tagyu, I’ve going to accomplish this by placing a <versions/> element in the XML file. This element will provide access to the previous, next, and latest resource representations as well as a reference for which one is being used currently. Instead of referring to versions with version numbers, I’m using the date that the version was released, simply because this date has more meaning than an arbitrarily-chosen version number.

<versions>
	<version rel="this" date="2006-01-12" href="http://tagyu.com/api/2006/01/12/"/>
	<version rel="previous" date="2005-11-02" href="http://tagyu.com/api/2005/11/02/"/>
	<version rel="next" date="2006-02-14" href="http://tagyu.com/api/2006/02/14/"/>	
	<version rel="latest" date="2006-02-15" href="http://tagyu.com/api/2006/02/15/"/>
</versions>

The latest version of the REST data will always live at tagyu.com/api/ without a date modifier as well as a URL with the date modifier. In the example above, the latest version is both at http://tagyu.com/api/ and http://tagyu.com/api/2006/02/15/. Clients that need a particular version should ensure they request the correct representation by using the date format.

The REST documentation will also list all alternate versions of the representations, and the documentation for each version will be available as well.