After reading a few comments on reddit and by email about my post on versioning of REST APIs I see that I wasn't clear on terminology and have left out some context. That's okay! Overthinking details is the main killer of all my interesting thoughts :-) I'd rather post more and repeat myself on occasion.

What's "backwards incompatible", exactly?

The main point of contention was that there's no problem, really: if an API changes incompatibly, existing clients could just use the old version of an API. Hence, a version bump in the URL is seen as a solution, letting many versions to co-exist in the public space. There was even a suggestion to keep all versions indefinitely.

Well, consider these situations, off the top of my head:

I'm going to go ahead and even postulate this:

if you are able to keep an old version of the API working alongside a new one, you shouldn't make the change backwards incompatible at all.

Why invalidate clients

So, when old functionality eventually dies, even after you supported it for some time, the clients that use it are invalidated. It is not a question of "if".

The question is, then, "how":

The crux of my argument in the previous post was that the latter is better because it avoids invalidating clients that don't use the broken resource.

A simple to imagine example would be a read/write API, like Twitter's. If you change the writing, your clients that only read don't even need to know about it. Which may be a majority of them. Or change in the authentication protocol that doesn't affect anonymous clients.

Miscellaneous

This bit caused some confusion, too:

It constrains development on the server as you have to synchronize releases of independent backwards incompatible features to fit them into one version change.

Here, I shouldn't have used the word "have". What I meant is that since you want to minimize the amount of breaking changes, you might want to shove many little breaking changes that's been cooking up in your code base into one public update. This requires synchronizing.

But I admit that, while completely real, it's rather a weak point.

Add comment

Format with markdown