March 24, 2021

Best Practices For Your API Versioning Strategy

API Lifecycle Management

When your APIs outgrow their original scope, you will need to modify them to adapt to changing requirements. Obviously, API versioning isn’t something that happens at random. Unlike server maintenance, it won’t happen at regular intervals either.

If you are creating a new version of your API, you are likely seeing a big shift in consumption, or changing the functionality of the software your API is built upon. Yet, smaller bug fixes might not require versioning seeing as the general goal is to keep an API version as stable as possible, while avoiding any breaking changes for consumers.

What Is API Versioning?

API versioning enables developers to leverage improved iterations of your API. Ultimately a part of API design, API versioning often accommodates API consumption changes, structural API shifts, and modifications to the underlying software or program which the API has been built upon. Backwards compatibility, documentation, business requirements, security, and scalability are all critical factors in API versioning. 

There are dozens of resources available to help you build, manage, and retire your APIs. When it comes to API versioning, opinions differ on how to best proceed. In the following paragraphs we will discuss API versioning best practices, explore different methods for versioning, discuss documentation, and explore how Akana can support your versioning strategy.

Why Is API Versioning Required?

If done haphazardly, API versioning can have disastrous effects on downstream products and services. So, why even bother? Like any other technology, APIs are interconnected and rely upon various systems, software, and databases to function. As the technology landscape continues to drastically shift, APIs must adapt their requirements, documentation, consumption protocols, and structure in order to keep up.

It is only in rare circumstances that an API will not require versioning. Most APIs outgrow their original scope, or require bug fixes. Although, a well-planned API could reliably function without intervention for many years, if the planning team had accurately forecast all competing variables.

Versioning Is Important in the Lifecycle

Versioning is an important part of the API lifecycle. But do you know everything there is to know about creating, controlling, and consuming APIs? Explore the hub and become an expert today.



How Do I Support Multiple Versions of an API?

If you haven’t run into this issue yet, you will. As your API management efforts grow, the complexity of your footprint will likewise escalate. Creating new versions of an API will not guarantee your API consumers will adopt these new versions right away, if at all. Which means you will need to accommodate backwards compatibility or support multiple versions of an API running in parallel.

There are two recommended approaches to resolving this issue, described below.

Versioning Through URI Path

Your universal resource identifier (URI) acts as the parent path for your URL. Or more simply, if your URL were a page in a book, your URI is the book itself. URI path versioning is Akana’s preferred method, and the industry gold standard. This approach is common among many of the leading technology players who have built their businesses around APIs. We’re talking Facebook, Airbnb, Twitter, the whole lot of them.

How to Do URI Versioning For APIs

If you are making a breaking change to your API, meaning any change that could break a client’s application, it is important that your API consumers know the change is being made. This patch is typically reserved for bug fixes. Here are two common scenarios.

Major or Minor Patch

There are different ways to communicate to API consumers whether you are making a major or minor patch.

  • Major patch: In this approach, your URI would denote the breaking changes to the API. A new major version requires creating a new API. The version number is what you use to route to the correct host via your URI.
  • Minor patch: You update change logs to inform API consumers of new functionality or bug fixes. Or, you could correlate minor to a lifecycle coordinator iteration, in which that minor introduces a non-breaking functionality.
  • Patch versions: These are made open and available to the client and used internally for API backwards-compatibility. These are also commonly communicated via change logs.

So what if you have multiple versions of an API running? In this case, leave your first version running and put a deprecation timeline in place for clients to move to version two. The deprecation timeline could, in theory, be infinite. If the change is non-breaking, simply iterate V1 API in the platform and underlying implementation. If you wish, you could use lifecycle coordinator to track iteration history of specific APIs.

API Versioning Through Content Negotiation

The second option for API versioning is to use content negotiation. This approach versions resources based on their representational state, or media type. We typically do not recommend this, but some organizations have success with this approach. If you are utilizing content negotiation to version your APIs, consider a few of the following points:

Strongly Typed Interfaces Will Not Be Possible

Strongly typed interfaces will not be possible, from the API platform and visibility enforcement standpoint. Which means, it will be difficult to trust the client app to match with the underlying implementation selected by content header version.

Virtual Service (API Proxy) Utilization

You will need to utilize a virtual service (API proxy) in order to allow multiple versions and implementations to funnel through.

The above process will prevent managing and contracting each API version separately. You will have no idea which apps are using which versions of your API, and whether it is safe to retire old versions.


This approach is also less accessible than URI-versioned APIs. When you require HTTP headers with media types, it is more difficult to explore the API using a browser.

Overall, content negotiation is a more granular approach. It versions resource representations instead of versioning the entire API. Likewise, it comes with a high implementation cost for clients and developers. More often than not, content negotiation needs to be implemented from scratch because there are few API libraries that offer it out of the box. 

API Versioning With Akana

With Akana, you can easily version your APIs and avoid breaking your API consumer applications. In addition to versioning features, we offer end-to-end security and full lifecycle API management. We have enabled dozens of clients across a variety of industries to gain efficiency in their API management. This includes large global banks, farm equipment manufacturers, B2B software companies, and more.

No matter your industry, Akana can support a comprehensive versioning strategy. You can get started with Akana today. Try it free for 30 days or watch an on-demand demo to see Akana in action.

Start Free Trial ▶️ atch Demo First