I've got an interesting comment on "Versioning REST APIs" that boils down to these points:
- Sometimes you can't really afford breaking clients (ever, or long enough to make no matter).
- 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:
- You want to abandon the old code base and don't even want to maintain header-base routing code in your new one.
- You're changing semantics of resources, effectively making it a completely different product.
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.