I've got an interesting comment on "Versioning REST APIs" that boils down to these points:

  1. Sometimes you can't really afford breaking clients (ever, or long enough to make no matter).
  2. A global version allows to freeze an old code base and have new implementation to be completely independent.

This is a different situation from the one I had in mind where breaking changes do eventually happen at some point.


Technically, no matter how you look at the issue, per-resource versioning gives you more flexibility than a global version number: changing version of every resource representation has the same effect as changing the global number.

From a practical standpoint it is as simple as having code somewhere checking the Accept header in all requests:

Accept: application/mytype+json; version=2

… and doing different things or even dispatching to completely different services depending on the version.

Even if you want to invent a completely different URL scheme for your API, it's still technically either changing representations of existing resources, or adding new ones (we can't remove anything under condition 1.)


I could see a tangential benefit in having a global version only in cases such as these:

But replacing the whole Universe with the new one does (or should) happen much less often than resource-local breaking changes that could be handled by per-resource versioning without affecting the whole API. If global version is your only mechanism than you have to change worlds all the time, even when you don't have to.

Comments: 1

  1. ruv

    Someone had to post this link: Web API Versioning Smackdown by Mark Nottingham. There are many similar thoughts.

Add comment