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.

This is the blog of Adam Kalsey. Unusual depth and complexity. Rich, full body with a hint of nutty earthiness.

Development

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.

Recently Written

Video calls using a networked camera (Sep 25)
A writeup of my network-powered conference call camera setup.
Roadmap Outcomes, not Features (Sep 4)
Drive success by roadmapping the outcomes you'll create instead of the features you'll deliver.
Different roadmaps for different folks (Sep 2)
The key to effective roadmapping? Different views for different needs.
Micromanaging and competence (Jul 2)
Providing feedback or instruction can be seen as micromanagement unless you provide context.
My productivity operating system (Jun 24)
A framework for super-charging productivity on the things that matter.
Great product managers own the outcomes (May 14)
Being a product manager means never having to say, "that's not my job."
Too Big To Fail (Apr 9)
When a company piles resources on a new product idea, it doesn't have room to fail. But failing is an important part of innovation. If you can't let it fail, it can't succeed.
Go small (Apr 4)
The strengths of a large organization are the opposite of what makes innovation work. Starting something new requires that you start with a small team.

Older...

What I'm Reading