Versioning an API is a river delta of pain

Slight rant: versioning a (REST) API inflicts upon you a confluence of factors that will lead to pain no matter what you do.

You’re going to need to version things, which opens you to bikeshedding which True Scotsman approach to REST versioning you’ll use. Once you’ve expended tons of effort on how clients should specify which version they want (i.e. once you’ve just barely started), now you need to figure out how to make that work in your code. Which, after you’re done parsing the HTTP request (the easy part!), is almost certainly going to lead to some unruly layer(s) of indirection. At which point you’re going to hate life and never want to introduce another version ever again. And you won’t even be close to finished.

I hope that, between JSON API and GraphQL, letting the client specify what they want ends up proving way better than relying on the server to carefully (or possibly carelessly) hand craft just the right data for the client.

One thought on “Versioning an API is a river delta of pain

  1. This is something my team have discovered over the past year, and is an area in desperate need of attention by the community, we’ve followed JSON-API as our standard, yet there are still holes with this: a lot of libraries freak-out if you introduce a new data type, so you still need some form of versioning to ensure you protect remote implementations from receiving data they are unaware of.

    To avoid reimplementing every serializer/controller/view for every version, we initially explored having a set of API “gates” whereby the input and output would be filtered depending on the version of the API the client is working with – therefore letting us have a single version of our API. But in the end, we have agreed on simply versioning our views, and if you’re working within Rails, I can recommend Version Cake ( for this as it’ll handle inheritance (so you if someone requests v4, and you only have v1, v2, v5 of a particular endpoint, it will render v2).

Comments are closed.