When it comes to Application Programming Interface (API) versioning, you’ll find many experts on the internet advising you on how you should approach it. Unfortunately, most of the advice is contradictory and inconclusive.

Every expert has their own opinion about how and where you should put the version identifiers. Some might even try to convince you that versioning isn’t necessary at all. So who will you listen to?

While API versioning is critical, there is no one right way of doing it. Instead, it’s important to understand the best practices associated with versioning to decide which strategy is suitable for you.

The Importance of API Versioning

API versioning refers to the various methods to differentiate versions of an API’s development. It accommodates structural API shifts, consumption changes, and underlying program or software modifications.

It’s a good idea to learn versioning along with the basics of APIs so that you are prepared to adapt your implementation as your API outgrows its original scope. You need the software to adapt to changing requirements, but it isn’t required to happen at regular intervals. You only need to up-version it when some significant changes occur.

A smart API versioning policy can help ensure stability and reliability. Improper API versioning practices or no versioning can leave disastrous effects on downstream services and products in the long run. You can expect to pay at least $40 an hour for an experienced developer, yet even long-time developers might not know the first thing about proper API versioning.

Since APIs are interconnected, they rely upon various software, systems, and databases to function. Like any other technology, APIs are dynamic, continually undergoing drastic shifts. So, you as the developer need to update their documentation, requirements, consumption, structure, and protocols to keep up.

This is why versioning APIs is necessary. An API’s original scope is limited, and it might outgrow it sooner or later. Moreover, APIs often need debugging and troubleshooting. You can minimize the need for these revisions by building a well-planned API that can reliably function without intervention for many years, but still, you will most likely need to version as you expand your program scope.

How to Version APIs

Unlike some other API standards, there is no one way to version appropriately. Still, there are some best practices for different use cases:

1. ‘Accept’ Headers

A server is told the information about a file format of the data that the browser requests through an ‘Accept’ header. The name for these file formats is MIME which stands for Multipurpose Internet Mail Extensions.

To implement ‘Accept’ header versioning, we can include additional parameters in the header to send out more data with the request. For instance, we use version parameters to define the service’s version that we need.

Now, when the version parameter is defined as part of the Accept header, the client will get the response in the specified version it requests.

2. URI Path

The Universal Resource Identifier (URI) is the URL’s parent path, and you can number the API version in the URI path. URI path versioning is the industry gold standard. Many industry leaders who have built their businesses around API like Facebook, Twitter, Airbnb, and others, have been using this approach.

Typically, this patch is reserved for bug fixes, but you can use it for API versioning as well. Here are two common scenarios for use:

• Major patch: In this patch, your breaking changes will be denoted through URI. However, you need to create a new API for a new major version. You will use the version number to route to the correct host via your URI.
• Minor patch: API consumers are informed about new functionality or bug fixes through the updated changelogs. Or, minor patches can be correlated to a lifecycle coordinator iteration, in which a non-breaking functionality is introduced through that minor.

If you have multiple running versions of an API, you can leave a deprecation timeline for the clients that asks them to move to version two.

3. Query String

Although a query string is used to query data, you can also use it to include a version in your API. While some might consider this a violation of a query string’s original purpose, it is an innovative use of queries to form a version control on your data.

For instance, if you publish a new article, it will be the article’s first version. Later you find some mistakes in the article, so you fix them. So, when the article is published with these changes, it will be called version 2. The query string allows you to make a GET request to /api/article?v=1 and lets you retrieve the first version. And if you wish to retrieve the second version, you can make a request to /api/article?v=2.

This method follows the REST convention, indicating that you can filter the requested resources using a query string.

4. Subdomain

This is one of the most common API versioning methods. Using a subdomain to host your API has plenty of advantages, but the biggest one is that you can use different servers to host your API from your leading site. In addition, API management services often route calls through a subdomain. Usually, the API provider becomes available without rate limits relying on private service.

The most common API subdomains include:

• api
• ws
• web services
• search
• services
• secure
• apis
• app
• dev

Versioning on the subdomain is not the same as hosting an API on a subdomain. In fact, it is possible to version while hosting on a subdomain at the directory level. This might be the most common combination, but you can also version using subdomains, such as:

• apiv1
• api-v1_1
• api2

Even though this method is really just as simple as changing the base domain, it is much less common.

5. Custom HTTPS Headers

The primary alternative for putting a version ID in the URL is to put it in an HTTP header. You can pick an option based on whether your aim is format versioning or entity versioning. If you’re going with format versioning, the version identifier will go into an HTTP header and not the URL.

To make things easier to understand, consider a bank. Conceptually, it is simpler to have a unique URL for each account regardless of the format that the API client wants to see it in. When you add a format version identifier in the URL, you effectively make a separate web resource for each entity’s format, and the changes in one can easily be transferred to the other.

This can be quite a complex model for users and also creates problems with the links. Say the bank has a secure, cloud-based API where they keep the customer records. Each customer account has a link for their records.

Some APIs have created canonical URLs for each entity to solve the link problem. So, they put version identifiers in URLs but maintain a set of version-specific URLs for the same entity. Clients convert the canonical URL to a version-specific URL when they want to follow a link.

Wrapping Up

There’s a lot of ambiguity around API versioning, making it difficult for people to choose a fitting technique — it’s easy to feel overwhelmed by all the available options. All of these techniques have different uses and consequences, so it’s essential to understand the different API versioning options, so you know when to use each.