Versioning REST

Freshness Warning
This article is over 11 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

  • Google on the desktop Google picks up Picasa, giving them an important foothold on people's PCs.
  • The importance of being good Starbucks is pulling CD burning stations from their stores. That says something interesting about their brand.
  • Lock-in is bad T-Mobile thinks they'll get new Hotspot customers with exclusive content and locked-in devices.
  • Newly Digital Newly Digital is an experimental writing project. I've asked 11 people to write about their early experiences with computing technology and post their essays on their weblogs. So go read, enjoy, and then contribute. This collection is open to you. Write up your own story, and then let the world know about it.
  • Rounded corners in CSS There lots of ways to create rounded corners with CSS, but they always require lots of complex HTML and CSS. This is simpler.
  • More of the best »

Recently Read

Get More

Subscribe | Archives

11

Recently

My Travel Coffee Setup (Jan 20)
What my travel coffee brewing setup looks like, and how you can build your own for under $100.
Turkey Legs (May 30)
Product naming gone awry.
Speaking for Geeks: Your Slides (Dec 17)
Tips and tricks for creating great slides.
Speaking for Geeks: Writing Your Talk (Dec 14)
Don’t wait until the night before the talk to write it. Crazy, I know.
Speaking for Geeks: Tell a Story (Dec 13)
Telling a story keeps your presentation focused, keeps your audience interested, and makes it easier for you to remember your talk.
Speaking for Geeks: Where to speak (Dec 11)
You've got a great idea for a talk. How do you find conferences to submit it to?
Speaking for Geeks: Getting your session accepted (Dec 10)
Your conference speaking submissions are not getting accepted because they're bad. Here's how to make them better.
Speaking for Geeks: What Should I Talk About? (Dec 9)
Don't wait for that conference to come calling before you start planning for it.

Subscribe to this site's feed.

Elsewhere

Tropo
Voice and communications platforms, including Tropo and Phono. Work.
SacStarts
The Sacramento technology startup community.
Pinewood Freak
Pinewood Derby tips and tricks

Contact

Adam Kalsey

Mobile: 916.600.2497

Email: adam AT kalsey.com

AIM or Skype: akalsey

Resume

PGP Key

©1999-2017 Adam Kalsey.
Content management by Movable Type.