What is API versioning? and why there is no right way to do it?

Published on 2021-08-23

API versioning is done differently by different companies and teams. It is a way of providing a stable, consistent and properly managed API, while allowing you to make breaking changes to an API while guaranteeing you don’t affecting your API consumers.

Changes in your API are inevitable, as your API grows, and your product develops, you need to be able to iterate quickly as it evolves.

When to version your API?

You should ideally version your API from day one, and there are many different ways of doing this, though it might not be clear when you should change the version.

You should change the version of your API, while keeping your existing version assessible to current API consumers, when breaking changes are made.

What is a breaking change?

Some examples of breaking changes are:

  • Change in the format or structure of the response for API endpoints
  • Renaming fields and/or resource paths
  • Change is response type (changing an integer to float)
  • Removing an endpoint or response
  • Change in required params
  • Changing API response status codes, HTTP verbs, or inconsistencies

What is a non-breaking change?

  • Adding new endpoints
  • Adding new response data

Types of API versioning

These are some of the most common ways of versioning your API. There is no right or wrong way of doing this, find one that works for your team.

Global URI Versioning

This is the most common method of API versioning, our API is versioned in this way, it works for us and it’s one of the most effective.

The version forms part of the URI, as either a prefix or a suffix e.g api/v1. Easy right?

It does however have it’s limitations, as an API grows it can become very rigid and inflexible. Its not possible to update a single resource or a subset of the API. Creating a new version everytime you make breaking changes can be time consuming, and can slow down iterations. We use it as we currently have a very simple API.

Resource Versioning (URI-based)

Similar to Global URI Versioning, but at the specific resource. You might have 2 endpoints api/v1/users and api/v1/products. If the products endpoint changes and needs a new version you could create api/v2/products, leaving the users endpoint to untouched.

This makes it easier for API consumers to make upgrades as they can focus on only the endpoints that require their attention.

However, as the API grows you might end up having to support multiple versions of endpoints, v1/v2/v3/v4 etc. It can also be easy to introduce inconsistencies between endpoints.

Query Parameter Versioning

A query parameter versioning approach is quite effective, you can pass the version as a query parameter.

For example:

api/products?version=1

This approach is very simple to implement, and it also makes it easy to make the latest API version the default, unless a version is specified. You do however need to ensure that your API consumers know when breaking changes are coming, so that they are prepared, and are passing the version as a query param.

Custom Headers Versioning

This method allows you to specifiy the version with a custom header containing the API version number.

For example:

Curl -H "accepts-versions: 1:
https://callcounter.io/api/events

The main difference is that no clutter is added to the URI.

Summary

Versioning an API is a critical part of API design allowing developers to improve and change their API without worring about introuducing breaking changes when new updates are rolled out. There is no “best” way of versioning an API, and we have only cover a few different ways with examples. As your API evolves you might change the way you version it, so choose a strategy, have a plan, and communicate that plan with your API consumers.

Blog index