Why and How you should version API?

7 Min Read

Vyom Srivastava

Do you know about 80% of data is being transferred through API? Well, that’s a lot of shares. Imagine you have an application that has more than a million users and suddenly the API stops working. All endpoints start to fail due to the new update. The other developers who’re connected to your API will start to complain, your users will not take your application seriously and your revenue will start to drop. Nightmare right? Now, this is what we’re going to cover in this article. How and Why you should version your API?

Why is versioning important?

API versioning is quite important because clients can be making requests to existing API’s and if you make certain changes you could break their existing calls. So versioning is one way to indicate that you’re making a breaking change to your implementation. So from an API versioning perspective, the term that you may hear is semantic version so the full semantic version is for something would be three digits ‘1.0.0’ indicating a different type of change. So this ‘1’ up in the front is the most important one from a versioning perspective because this will dictate whether or not you’ve made a breaking change. So this ‘1’ here is very critical. This is your major version number. You shouldn’t have too many of the major versions. So, if you’re doing things sensibly and trying to keep the amount of change that is of breaking nature to a minimum.

There are going to be a lot of requests for additional functionality and that’s what this second one ‘0’ is about. So the second one is minor so this is when you’re updating the API to do things like adding a new operation in the restful world. It is a non-breaking action because anyone who’s got an existing operation can still call it and they just ignore the new one. And for anything else you’ve got this other spot which is’0’ it is for patch type releases so.

Now, let’s look at some examples of why you might need to do a major version change. So let’s say you’re dealing with an API and you have a need to add a new mandatory input. Now, if you think about existing consumers they are not going to be feeding in that mandatory input so if they tried to call the same endpoint they would be told you have not supplied enough data. So, this would be a breaking change for existing consumers if you remove functionality or rename so renames are the same as remove and then an addition of the new function. So as far as removing or renaming now this could be something like afield as well so if you have expected a certain field to come back and someone removes that then it is quite likely that if it was something you’re reliant on you could have problems on client-side so it would be something that you would need to increment the major version so that would be a version two of your API

When you should version the API:

You only need to version the API when a breaking change is done. Some of the major breaking changes are the following :

  • Some changes in the format of the response data for one or more than one call.
  • Some changes in the request or response type i.e. swapping an integer to afloat.
  • Removing any part of the API.

Why versioning is required in web API: Versioning is required in Web API because once web API services are made public, different client applications start using and relying on the service. As the business grows and requirements change, the services need to change without breaking existing clients and at the same time satisfying new client requirements. This is when the web API version helps. It keeps the existing services at ease so we are not breaking the existing client applications and develop a new version of the service that new client application can start using

API Versioning methods

There are different methods available for versioning the API. Let’s have a look at some of these.

  • Versioning through URI path
  • Versioning through query parameters
  • Versioning through custom headers
  • Versioning through content negotiation

Versioning through URI path

In this versioning method of API, we include the version number in the URI path. Many DevOps teams at Facebook, Twitter, Airbnb, etc. use this strategy in the versioning. Using the URI is the most simple approach and it is also the most used version. Even though it contradicts the fact that the principle that a URI should refer to a different and unique resource. And there is a strong chance that you’ll break the client integration when a version is updated. Also, the version doesn’t need a numeric nor the “v[x]” syntax.

There are some pros and cons for using this which are following as:


It gives the client an advantage because with that clients can easily cache resources.

Cons: This solution introduces the breaking changes involve branching the entire API


Versioning through query parameters:

In this versioning method of API where you specify which version you want to retrieve in a query string parameter. This is the most direct way to version an API, it’s easy to default to the latest version. E.g. http://localhost:7500/api/Categories?v=1.1 So this is a query string parameter the moment you put a question mark it becomes the query string parameter. So basically, after a question mark, you have a key-value pair.


This is the most direct way to version an API, and the most important thing it’s easy to default to the latest version.


The problem with this is the query parameters are hard to use for routing requests for the proper API version.


Versioning through Content headers:

In this versioning method of API, a custom header allows you to secure your URIs between different versions. It is done by including the version number as an attribute of the custom headers. It is somehow very similar to content negotiation. The only major difference between this approach and the two above approaches is that it doesn’t make a mess of the URI with the information of versioning.


The best thing about this method is it doesn’t make a mess of URI with versioning information.


The only problem with this method is that we have to make custom headers for this.


Accept-version: v1
Accept-version: v2

Versioning through content negotiation:

This approach allows you to version a single resource representation instead of versioning the entire API. Which gives you the power to control over versioning. The best thing about this is we don’t need to split the whole application while building the new version because it creates a small footprint in the code that helps us to do that. The biggest advantage of using this is it doesn’t require implementing URI routing rules introduced by versioning through the URI path.


This method doesn’t require much change to identify the requested version which helps to reduce the development time.


The most common issue with this method is that you can not test this method from the browser.


Accept: application/vnd.ploeh.user+json; version=2

Best practices for API versioning:

We have covered a lot about API versioning but there are a lot of checkpoints that also need to be followed. So here are some of them:

  • Your API should also support previous versions, this is known as backward compatibility. But why should it? It’s because there could be millions of consumers and a lot of consumers won’t upgrade or start using the new version right away. The good practice is that your API should support the last two versions at max.

  • Your new endpoints should not conflict or not even match with the existing endpoints. For example, You already have the /apple endpoint and you have created the /apples endpoint which returns something else. Do you think it’s a good idea?

  • Always mention the expiration date of the API version in response headers.

  • If someone is using the older version, you should also notify the API consumer in the API responses.

  • If you're removing an API endpoint, make sure you return 302 response code.

Tools that you can use for API versioning:


Git is the most popular open-source tool for version control of code. It allows multiple developers to collaborate, create branches in a repository, and merge them. This is being used by some big companies like Google, Microsoft, IBM, etc. Git supports distributed workflows, maintains data integrity, and also tracks any change in the file. A few of the Git clients are Gitlab, Github, BitBucket, etc.


  • Very easy to use and has a very big community
  • Works seamlessly on any platform
  • Very flexible
  • Easy to revert the changes and merge the changes


  • You’ll have to deal with a lot of commands
  • Sometimes there could be conflicts due to white spaces.
  • Lack of GUI client for Git.


Apache Subversion or SVN is another version control software that is open source and supports distributed workflows. It uses a timestamp to validate the changes which allow you to recover older versions depending on the timestamp. The most popular client for SVN is TortoiseSVN.


  • It has better support of UI unlike Git
  • Easy to set up
  • It has less complexity than Git


  • It does not support signed revisions
  • Not much widely used than Git

There are a lot of other version control softwares available that you can use, but we have listed the most popular here.

Final Words:

API is a very important part of the internet because without API certain things won’t be possible. Almost at every signup page, there is an option to sign up with Google or Facebook that is because of API. An API is something that is helping you to have seamless connectivity, you don’t feel that you’re getting connected with so many things but that API is helping.

When working on the API, you’ll have to follow some basic rules which are mentioned in this article, and also document them in such a way that it is easy to understand and consumers who’re migrating from an older version to a newer version can migrate seamlessly. We have covered most of the API versioning methods here and if we have missed any of them, you can let us know in the comments we’ll consider adding them in the article.

Why is versioning important?When you should version the API:API Versioning methodsBest practices for API versioning:Tools that you can use for API versioning:Final Words:

Popular Posts

Getting started with GraphQL

GraphQL is a query language designed to build client applications by providing flexible and intuitive syntax for asking the data requirement by clients.

Vyom Srivastava

7 Min Read


DownloadDocChange LogsCookiesTerms & ConditionsPrivacy PolicyContact Us

Apps & Integrations


Firecamp Newsletter