Why should I version my API?

February 14, 2020

This is part of a multi-part series on how to version your API.

We often hear a lot of questions and confusion around versioning your API so we are starting a whole blog series on versioning.

We'll start by answering the basic question of, "Why should I even version my API in the first place?"

But Why?

To answer that, let's suppose how things would work if you didn't version your API.

Let's say you were building a currency-exchange API. Hit the API and see the latest exchange rates between various rates US dollars, the Euro, the Peso, etc. You launch the API and everything is going well into someone at your company decides they want to change your pricing structure. Perhaps they want to limit the number of API calls that can be made by a certain pricing tier or only want to expose some data to premium customers.

At this point, you all agree this is the best decision and now how to figure out how to implement it. Then you start thinking through the implications of this and realize that, while implementing the actual change is trivial, doing so and just pushing it will cause some client implementations to break. Their code will suddenly start seeing some 402 Payment Required responses causing their app to break and leaving you with some very unhappy customers and very bad PR.

Moreover, even if you gave the clients plenty of time to make the change on their side, some of them would update their code sooner than others. You want to be able to support both the fast-moving and slow-moving customers at the same time but are unsure how to.

Versioning to the rescue

This is where versioning comes in. You can think of versioning as kind of like a feature flag; a top-level fork in the road that sends some API requests down one logic path while others go down another. It allows you to push out a new interface to your API without immediately deprecating your old interface. This is achieved with a simple version identifier letting you know which interface an incoming request is for.

In this case, if your currency API launched with an initial version, you could implement the modified interface in a new version and give your customers a grace period to adjust. Problem solved.

Versioning is relevant for human-facing applications too. Just ask doctor or anyone else who spends a huge amount of their day entering data into a system like Epic. If the UI changes under their feet suddenly, they will be frustrated about where to implement the necessary workflows they do dozens of times a day. That is why those UIs are often "versioned" to with the ability to toggle between the new and old views with a grace period for people to get adjusted.

However, versioning is extra-important in APIs which are consumed by machines which are brittle to tiny changes. In a sense, your API is not a stand alone application but instead a component within several larger applications as implemented by your customers, and you need to start thinking of it as such.

With versioning you can manage change more effectively. It allows you to evolve your API while allowing clients to adjust to your changes at a pace that works for them.