Methods of Versioning APIs

There are different ways in which we can create versions in APIs. Widely used methods are explained below

1. URL Versioning

In this approach we will add version number in the URL.

• If the normal URL looks like http://localhost:8080/get-books,
• Then it will become http://localhost:8080/v1/get-books and http://localhost:8080/v2/get-books.

Note: Problem with this approach is that it will clutter the URL and thus this is not good for long term maintainability.

2. Query Parameter Versioning

Here we will append the query parameter named as Version or any of your choice which is not used any where else. And as a value we will give its version number.

Example:

Before: http://localhost:8080/get-books

After: http://localhost:8080/get-books?version=1.0 and http://localhost:8080/get-books?version=2.0

This will keep the main URL but it will add the bottleneck of parameter and thus sometimes it may be less intuitive for clients.

3. Header Versioning

This method is used when we don’t want change the URL any how by now adding version number in URL or by adding query parameter. So thus we will add one Header in Request known as “X-API-Version”. So the request will look likes

GET /get-books HTTP/1.1
Host: localhost:8080
Accept: application/json
X-API-Version: 1

Here the URL is not tempered but the only problem is that client may require additional effort to manage the version header.

Let’s understand this with some real time examples and for that here we are taking a example of Library Management System where we have a microservice which manages book. And now we have to create a another version of some APIs.

REST API is widely used when it comes to communicating between two microservices. And thus maintaining it is again a major task. We also have to make sure that while developing new functionalities we don’t interrupt the working functionalities because it may create a major problem in other services. Thus we have to do versioning of the API which adds up the new features keeping others as it is.