Adam Kalsey

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

Versioning web services

14 Feb 2006

When I add a new feature to Tagyu’s web service API, how should I best version it? I don’t want to maintain and support multiple, old copies of the API, but I also need to ensure I don’t break backward compatibility. A change to the API can’t cause existing apps out there to stop working.

At first I thought this was an easy problem. I’d simply ensure that any time I made a change to the API the changes would be additive. I wouldn’t remove any data, I wouldn’t change the location of representation of the data, I’d only add new data. If a case came up where I needed to change how the XML data is stored, then I’d consider maintaining parallel versions of the API for a period of time. I’d figure out how to do that when the time came. Amazon Web Services inserts their API version into the URL, but that’s always seemed a bit clunky to me.

Today’s new API feature made me rethink how I change the API and represent different versions. It made me rethink what changes should be even considered as a new version. Today’s change involved the insertion of a couple of attributes to one of the XML tags. Shouldn’t be a problem right? That’s what I thought, too.

Before the change, the XML node for a suggested tag looked like this:

<tag>sometag</tag>

After the change, it looked like this:

<tag rel="related" href="http://tagyu.com/api/tag/sometag">
	sometag
</tag>

Those two new attributes broke some APi implementations, including my own software, the Tagyu Movable Type plugin. The plugin uses XML::Simple to parse the API’s response. And as far as XML::Simple is concerned, those two formats are completely different XML structures. XML simple represents the first one as this…

{
    'tag' => 'sometag'
}

And the second as this …

{
	'tag' => {
	 	'rel' => 'related',
		'href' => 'http://tagyu.com/api/tag/sometag'
		'content' => 'sometag'
	 }
}

The Tagyu plugin accesses the tag through $tags->{'tag'} but under the new structure, that’s not the tag at all, it’s a hash that contains the tag, among other things.

The point of all this is that even though I thought I was being careful, today’s API change broke things. And that’s bad. It should never happen.

I’m looking for thoughts on how to version a web services API or really any software that’s delivered as a service. How do you prevent changes from having adverse effects while at the same time providing improvements. Is different API versions at different URLs really best or only way to go?

Recently Written

Your OKR Cascade is Breaking Your Strategy
Aug 1: Most companies cascade OKRs down their org chart thinking it creates alignment. Instead, it fragments strategy and marginalizes supporting teams. Here's what works better than the waterfall approach.
Your Prioritization Problem Is a Strategy Problem
Jul 23: Most teams struggle with prioritization because they're trying to optimize for everything at once. The real problem isn't having too many options—it's not having a clear strategy to choose between them. Without strategy, every decision feels equally important. With strategy, most decisions become obvious.
Behind schedule
Jul 21: Your team is 6 weeks late and still missing features. The solution isn't working harder—it's accepting that your deadlines were fake all along. Ship what you have. Cut ruthlessly. Stop letting "one more day" turn into one more month.
VC’s Future Lies In Building Winners
Jun 21: AI and megafunds are about to kill the traditional venture model, forcing smaller VCs to stop hunting for hidden gems and start rolling up their sleeves to fix broken companies instead.
Should individual people have OKRs?
May 14: A good OKR describes and measures an outcome, but it can be challenging to create an outcome-focused OKR for an individual.
10 OKR traps and how to avoid them
May 8: I’ve helped lots of teams implement OKRs or fix a broken OKR process. Here are the 10 most common problems I see, and what to do instead.
AI is Smart, But Wisdom Requires Judgement
May 3: AI can process data at lightning speed, but wisdom comes from human judgment—picking the best imperfect option when facts alone don’t point the way.
Decoding Product Leadership Titles
Mar 18: Not all product leadership titles mean what they sound like. ‘Head of Product’ can mean anything from a senior PM to a true VP. Here’s how to tell the difference.

Older...

What I'm Reading