API Versioning: A Complete Guide

Introduction to API Versioning: Why It Matters

Imagine, You have developed an API and pushed your changes to the production. Now it is consumed by thousands of users across various different clients. The API is functioning well and business has decided to add new features to it.

Now let's say we want to change the contract to support the business requirements. This might break the client code if there is a change in the existing field name or change in the data type.

Forcing clients to update their code to consume new changes of API will not work, as not every client would be ready or may not require the new changes immediately.

API Versioning solves this problem of supporting the new changes without breaking the existing functionality.

So how can we implement the API versioning. There are different versioning approaches and we will explore these below.

Versioning with URI:

As you can see above, the URL contains the version number /v1 in it. This is the most easy and effective way of managing the versions of the API due to it's visibility across different layers of the system.

This method of managing versions is easy to debug and also facilitates monitoring tools to monitor the each version separately. However it involves some code duplication.

HTTP Header Versioning:

https://techstackengineer.com/api/articles
Headers: Accept: application/json; version=1.0

In this approach, HTTP header is used to indicate the version of the API. The most preferred header used for this approach is "Accept". This versioning method avoids the clutter in the URI as it doesn't include the version number in the URI.

This approach makes debugger harder because the version number is less visible. Also, If the new version contains many contract changes, the server side code will have complex logic.

Versioning with Request Parameter:

https://techstackengineer.com/api/articles?version=v1

In this approach, the version number is maintained at the request parameter level as you can see above. This approach is also simple just like URI versioning, however this approach maintains only one endpoint.

The server side code may have complex logic if there are multiple versions with different contracts for each version. Observability would also become difficult with this approach, because of one endpoint. If you want to know response times, total request count for each version, additional logic has to be done.

Versioning using Host Name:

This versioning method is generally used when there is a large scope change such as REST to graphQL etc. This approach involves extensive rework of an API and demands comprehensive documentation of changes.

When to Implement API Versioning

https://techstackengineer.com/api/v1/articles

{
  "articles": [
    {
      "id": 1,
      "name": "API Versioning",
      "category": "API Design"
    }
  ]
}

Let's take an example of JSON response above. This API returns list of articles in the JSON format and category a string data type. Now we have decided to modify the category data type to object so that it can carry additional details such as id.

This is a breaking change and the client code will break once the category field data type is changes from string to object. This should to be handled in a separate version. Clients can consume when ever they are ready and the old version of the API should still be supported until all the clients migrates from old version to new version.

https://techstackengineer.com/api/v2/articles
{
  "articles": [
    {
      "id": 1,
      "name": "API Versioning",
      "category": {
        "name": "API Design",
        "id": 1
      }
    }
  ]
}

Below table explains when to go for versioning of the API.

Conclusion

API versioning is a crucial practice for maintaining the stability and flexibility of APIs in a rapidly evolving business environment. By carefully choosing a versioning strategy—whether it's URI, HTTP header, request parameter, or host name—you can implement changes without disrupting existing clients.

Understanding when to introduce a new version ensures that backward compatibility is maintained, allowing clients to transition seamlessly and at their own pace. Effective versioning fosters a robust and scalable API ecosystem that can adapt to new requirements while preserving the integrity of existing integrations.