API versioning strategies - the real story

You will have heard about API versioning strategies if you provide APIs. Your development team might have had many conversations about the best choice, but I’ve got some news. Choosing where to put your API version number is not a strategic decision. 

The pace of the business and change

Your versioning strategy results from many choices your organization and clients have made. These range from which customer segments and industries to serve to which products and services to offer.  

 the relationship between your organization and your API consumers is a significant factor. It affects 

• how often you are changing your API,
• how often you are forced, or 
• Are you able to make any changes or break changes? 

How your API consumers will take your proposed versioning schedule depends on the power structure:

• if your API consumers depend on you, you can dictate when they will change versions; 
• some API consumers are more powerful and influential, or 
• the relationship is highly regulated.

‍

If you can make changes to the API and want to introduce the changes as new versions, then you need to solve the problem of how to indicate a version change.

‍

Tool capabilities dictate your use of version numbers

API versioning is different from code versioning. It’s not ok to increase your API version number every time the code implementing the API or the documentation changes. Only when the actual interface or, in some cases, behavior changes are you doing an API change. I always confuse people by saying APIs need 2 x DevOps. What I mean is that your API, the interface of it, possibly described by an OpenAPI definition, has one lifecycle, and the code implementing the API has its lifecycle.

To some extent, they are not dependent on each other. You can make a typo fix to your OpenAPI definition without changing the code or the calculation logic in the code without changing the interface, for example.

Your code should use semantic versioning, i.e., you should constantly be updating the version number with major, minor, and patches  1.1.1. The discussion around API versioning tends to start in new teams or APIs with: “Should we put the version number to URI Path, query parameters, custom headers, or use content negotiation.” But you are not having a free choice about it. And you definitely shouldn’t do it because it’s “good coding practice.” 

With each interface version number change, you API consumers have to change their code. And they don’t like it. It costs them, and their systems might break, even if the change wouldn’t cause them any problems.

Remember to check what your API consumers' technology and tooling, and even more so, your API management platform, can handle. Especially legacy tooling is picky and can only handle version numbers in the path. Some API management platforms are built to support API products or plans, where the changes to the API version can be hidden behind the product and subscription layer. 

If you are using version numbers to indicate changes to your API, consider only increasing it if you are introducing a breaking change. And only if that change breaks any clients from their perspective. It can get confusing sometimes, I admit. There are some exceptional cases where API consumers experience a change even if the API design is not changing.

One of our clients had a service disruption because an API provider suddenly changed the API's authentication method. I saw the email the API providers support had sent after our client had complained. The answer stated that “this was not an API change; we just changed the authentication.”  We could argue the semantics of that statement, but the bottom line is that the API consumer, our client, experienced a service disruption. So the change was breaking; it wasn’t backward compliant. No arguing over the experience of the API consumer here. 

If a feature in your API isn’t used, it can’t break.

I’m letting you in on a secret. If it isn’t used, it can’t break. If you start small, know your API consumers' needs, look at the logs and statistics to see if anyone is using the feature you are about to break or not, and otherwise keep adding only new endpoints and attributes, you can stick with the same major version and only that for years to come. You would only need a change when you do an extensive redesign affecting many or all endpoints or introduce significant business logic changes.

Let’s say you have just exposed a few endpoints with minimal attributes. You are sure that everything is needed, designed to perfection, and validated with future API consumers. Why not add things to the same API version and consider versioning the documentation or updating release notes? This way, those who have already plugged into the API don’t have to change their code and can just start using the new features.

There are exceptional cases, as always. One platform provider exposed new groups of personal data from an existing endpoint. This created a privacy breach and was a breaking change, even if the interface didn’t change. So when it comes to adding new features to the API, it’s ok, but watch out if those features are just more data. This example case ended with the 3rd party application provider being shut out of their business because they were blocked from using the API after customers found out about the privacy issue. And the application provider consuming the API had not done anything wrong, except maybe they should have had better testing policies. 

So, is your API team mature enough to produce minimum viable versions and do great API design and development? This will impact your need to introduce breaking changes or your ability to avoid them. Assess the team's capabilities for research and visioning the future needs of the API consumers. Where are your API products or the resources, services, or products they are exposing headed? 

‍

The evolving API versioning strategies

Your API versioning on a strategic level should evolve towards the changes in the value creation expectations of your API consumers, i.e., your internal teams, clients, or partners.

You might have started with a “Company X API.” You then realize this will be too big and expose too much to too many consumer segments. You might evolve as a company to offer multiple SaaS, data, or other product or service variations to which your API is tightly coupled. So you split your API per product and version according to your product versions.

Then you realize that there are some endpoints that

a) are common to many products or

b) are limited to only some specific API consumer segments. 

c) should have different pricing than others. 

So you end up splitting your API products according to value propositions or use cases.

This should be easy considering your depth of customer, partner, and API consumer understanding and your overall roadmap and product vision. Hopefully, you have them. The question is, how do you see your API evolving? What resources is it exposing, and what is its lifecycle? It does make a difference if the API is connected to a car instead of a machine-learning algorithm in the cloud. The latter will be easier and faster to change if the API changes.

In the end, you do things right and offer a fantastic API. Your API consumers haven’t noticed your API would often break (even if you have introduced all necessary changes). You provide a clear roadmap based on proper API consumer understanding. Your API consumers should be delighted and informed. They will innovate with you and help you create your roadmap. They are committed to making changes or adopting the new features you provide. After all, they were collaborating in the process.

Hope you will feel inspired the next time you need to think about API versioning strategies!

‍