API Versioning
Versioning is the term what computer software industry folks use. But the general/ equivalent term (at least as I believe) is the Evolution.
Evolution is something that we all go through and it’s applicable for every single object in this world.
Joe goes through different stages/ states in his life. It happens automatically and Joe’s evolution is beyond his control. But if we look at the house we live in, it may not be the same setup we used to live when we were kids. Due to various reasons, we had to modify/ enhance the house to cater to our current/ modern needs.
As we can see from the above example, change is inevitable. It applies to the computer software industry as well. We see every computer software comes with a different release/ version every 3–4 years to cater to the current/ modern requirements.
Versioning is the practice of the creation and management of multiple releases of a software product. It allows consumers to decide which version to use depending on their requirements. It very well applies to APIs as well.
The creation of an API always starts with an idea of enabling application integration with internal/ external application developers. Just like any other traditional software product, it always starts small and evolves over time. Let’s look at the below simple use case to understand it well.
For example, you may want to enable internal/ external application developers to access Customer information and you may start creating an API to provide the required functionality. As the first release, you may provide an API with only the Read access to the Customer information. Later, with the increasing demand of the application(s), your application developers may request Write/ Update access to the Customer information. As an API creator/ developer, you can decide whether:
- To provide a new version of the same API with Write/ Update access to the Customer information
- To provide a separate API altogether to provide Write/ Update access to the Customer information
The common API design principle is to use the first approach — provide a new version of the same API with the additional functionality as we are dealing with the same Entity — Customer, from the application developer perspective. This will result in having 2 versions of the same API:
- CustomerInfo v1.0 — provides Read-only access to the Customer information
- CustomerInfo v2.0 — provides Read/ Write/ Updates access to the Customer information
With the versioning of APIs, consumers of the CustomerInfo API can decide which version to use depending on their needs.
When we want to support multiple versions of the same API, as the API creator/ designer, there are 02 main design decisions which we need to consider:
- What will be the format for specifying the API version information
- How will the consumer specify the API version of the selected API
When selecting a format for specifying the version information, there are 02 common practices which we can select from:
- Use of release/ build date — this allows the use of release/ build date to identify each version uniquely.
Example — version=”8/8/2020” | version=”1/1/2019”
- Use of major.minor number — these are numbers that use specify different versions of the same API and it can contain 1 or 2 or 3 digits as part of the version number. Some API developers use “v” prefix to indicate that it is a version number.
Example — version=”1” | version=”v1” | version=”1.1” | version=”v1.1” | version=”1.1.1” | version=”v1.1.1”
When deciding how will the consumer specify the version information, there are 03 common practices which we can select from:
- HTTP Header — a custom HTTP header will be used to pass the API version information
Example — x-customerinfoapi-version:2.1
- Query Parameter — API version information will be passed as a query parameter
Example — /customerinfo?version=2.1
- URL — API version information will be incorporated into the URL itself
Example — /v2/customerinfo
As API creators/ developers, we can also combine some of the approaches above and provide a hybrid approach for providing API version information. For example, we can use the URL approach to specify the major version and HTTP header approach to specify the minor version of the API.
As you can see, API Versioning is a key feature in the API design/ development and as an API provider, enabling consumers to choose between different API versions is a key business differentiator.
Happy API Versioning….
