API Versioning Strategies

Through this blog, we'll explore the nitty-gritty of API versioning and address questions like when to do API versioning, how to implement it, and the strategies involved in the process.
Avinash Padalkar_avatar
Avinash Padalkar
May 13, 2022 | 4 min read

Why API Versioning?

Growing a business means dealing with lots of new changes. A client might suggest or demand new changes according to their business needs. We have to expand our services accordingly to meet all those requirements. However, while making these changes or providing new services, we must consider existing services and the client's expectation of backward compatibility.

Developing an API is always a challenging process. Some scenarios will involve major changes, and it may be necessary to rewrite everything to meet the requirement, and the original version is no longer required. Moreover, updating technology and delivering changes at the same time can be complex.

In such cases, API versioning plays an important role. We need to take care of existing services to ensure the current client applications do not break and need to develop a new version of the API service for the client.

What Are API Versioning Standards?

There are no API versioning standards that exist. Every company establishes its standards for the same.

However, there are some API versioning strategies that we would like to talk about in this blog.

API Versioning Strategies:

Below are some of the API versioning strategies that are widely used across many companies.

1. URI Path Versioning

Using the URI is the most straightforward and widely used method. We mention the version number in the URI path. Usually, we use the “v” prefix in the path in addition to the version number.

Example- oidc-flow





2. URL Parameter Versioning

We add a query parameter to the request that indicates the API version.

Example- oidc-flow


3. Request Header Versioning

This strategy lets you specify the version by creating custom headers using version numbers. We don’t need to modify the URL in this API versioning strategy. The headers handle the versioning. Also, this approach is easy to maintain and manageable and requires minimum code-related changes to implement.

Micronaut framework makes it very easy to use version numbers in headers. You just need to enable the versioning.

In the application.yml file we can enable versioning by setting micronaut.router.versioning.enabled to true. oidc-flow

1. Enables versioning
2. Sets default API version
3. Parameter-base API versioning- Specifies the parameter names as a comma-separated list
4. Header-base API versioning- Enables or disables header-based versioning. Specifies the header names as a YAML list

In the Controller class, we can define the version as mentioned below- oidc-flow

1. Enable default version on that controller class
2. The callV1 method is declared as version 1
3. The callV2 method is declared as version 2

Example- oidc-flow

URL http://api.example.com/user

Headers -

Accept-version: v1

Accept-version: v2

X-API-Version: 2

We can mention the date as well instead of version number X-MS-Version: 2022-03-03

4. Content Negotiation Versioning

Content negotiation involves selecting one of the multiple possible representations to return to a client based on the client or server preferences. This versioning strategy allows us to version a single resource representation instead of versioning the entire API, which gives us more granular control over versioning. It creates a smaller footprint and doesn’t require implementing URI routing rules. The content negotiation approach will not change the client URL, but the client must deal with the complexity of multiple versions. We will provide a resource based on the header specified by the client.

Example- oidc-flow

URL http://api.example.com/user





Sample Project For API Versioning

Below is the link to a sample project that we created for API Versioning- https://github.com/avinashpadalkar/api-versioning


All the API versioning strategies have their pros and cons. There are no fixed API versioning standards, and every company sets its own. API versioning deals with the changes and managing the breaking changes and requires efficient API change management principles. For most APIs, URI path versioning is the simplest solution.

We hope you find this blog informative and helpful. Visit us at medly.tech for more such technical blogs. Happy reading folks!