Versioning REST

Freshness Warning
This article is over 13 years old. It's possible that the information you read below isn't current.

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.

Your comments:

Text only, no HTML. URLs will automatically be converted to links. Your email address is required, but it will not be displayed on the site.

Name:

Not your company or your SEO link. Comments without a real name will be deleted as spam.

Email: (not displayed)

If you don't feel comfortable giving me your real email address, don't expect me to feel comfortable publishing your comment.

Website (optional):

Follow me on Twitter

Best Of

  • How not to apply for a job Applying for a job isn't that hard, but it does take some minimal effort and common sense.
  • Movie marketing on a budget Mark Cuban's looking for more cost effective ways to market movies.
  • California State Fair The California State Fair lets you buy tickets in advance from their Web site. That's good. But the site is a horror house of usability problems.
  • Customer reference questions. Sample questions to ask customer references when choosing a software vendor.
  • Comment Spam Manifesto Spammers are hereby put on notice. Your comments are not welcome. If the purpose behind your comment is to advertise yourself, your Web site, or a product that you are affiliated with, that comment is spam and will not be tolerated. We will hit you where it hurts by attacking your source of income.
  • More of the best »

Recently Read

Get More

Subscribe | Archives

Recently

Assumptions and project planning (Feb 18)
When your assumptions change, it's reasonable that your project plans and needs change as well. But too many managers are afraid to go back and re-work a plan that they've already agreed to.
Feature voting is harmful to your product (Feb 7)
There's a lot of problems with using feature voting to drive your product.
Encouraging 1:1s from other managers in your organization (Jan 4)
If you’re managing other managers, encourage them to hold their own 1:1s. It’s such an important tool for managing and leading that everyone needs to be holding them.
One on One Meetings - a collection of posts about 1:1s (Jan 2)
A collection of all my writing on 1:1s
Are 1:1s confidential? (Jan 2)
Is the discussion that occurs in a 1:1 confidential, even if no agreed in the meeting to keep it so?
Skip-level 1:1s are your hidden superpower (Jan 1)
Holding 1:1s with peers and with people far below you on the reporting chain will open your eyes up to what’s really going on in your business.
Do you need a 1:1 if you’re regularly communicating with your team? (Dec 28)
You’re simply not having deep meaningful conversation about the process of work in hallway conversations or in your chat apps.
What agenda items should a manager bring to a 1:1? (Dec 23)
At least 80% of a 1:1 agenda should be driven by your report, but if you also to use this time to work on things with them, then you’ll have better meetings.

Subscribe to this site's feed.

Contact

Adam Kalsey

Mobile: 916.600.2497

Email: adam AT kalsey.com

Twitter, etc: akalsey

Resume

PGP Key

©1999-2019 Adam Kalsey.