Need someone to lead product management at your software company? I create software for people that create software and I'm looking for my next opportunity. Check out my resume and get in touch.

Versioning REST

Freshness Warning
This blog post is over 18 years old. It's possible that the information you read below isn't current and the links no longer work.

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.

Sre
March 30, 2010 10:25 AM

What is approach to rolling out updates that are not backwards compatible? If you always have latest on the default/standard URL and have a change that is not backwards compatible how are going to deal with the endpoints that are going to break? Thanks, Sre

Adam Kalsey
March 30, 2010 10:36 AM

What I suggest is that apps keep track of the LATEST tag and ensure they always use a consistent version of the API until they have a chance to test. In fact, many apps would use a specific version instead of the standard URL. When LATEST changed, use that as a signal to look into the new API changes.

This discussion has been closed.

Recently Written

Mastery doesn’t come from perfect planning (Dec 21)
In a ceramics class, one group focused on a single perfect dish, while another made many with no quality focus. The result? A lesson in the value of practice over perfection.
The Dark Side of Input Metrics (Nov 27)
Using input metrics in the wrong way can cause unexpected behaviors, stifled creativity, and micromanagement.
Reframe How You Think About Users of your Internal Platform (Nov 13)
Changing from "Customers" to "Partners" will give you a better perspective on internal product development.
Measuring Feature success (Oct 17)
You're building features to solve problems. If you don't know what success looks like, how did you decide on that feature at all?
How I use OKRs (Oct 13)
A description of how I use OKRs to guide a team, written so I can send to future teams.
Build the whole product (Oct 6)
Your code is only part of the product
Input metrics lead to outcomes (Sep 1)
An easy to understand example of using input metrics to track progress toward an outcome.
Lagging Outcomes (Aug 22)
Long-term things often end up off a team's goals because they can't see how to define measurable outcomes for them. Here's how to solve that.

Older...

What I'm Reading

Contact

Adam Kalsey

+1 916 600 2497

Resume

Public Key

© 1999-2024 Adam Kalsey.