Versioning is the practice of creating collaborative data sharing and editing controls to ensure that your product continues to give consumers more choices without having to upgrade to the latest version. Versioning is an integral part of the API design. It arms developers with the ability to enhance their API without disintegrating the client’s applications when new versions are developed. Versioning permits clients to keep on using an existing REST API and only migrate or update their applications to the recently rolled out API versions when they are ready.
Types of API Versioning
The greatest challenge to exposing services is how to handle updates to API contract. Clients may not be ready to update their apps when the API changes, and this is where a versioning strategy becomes vitally essential. Different companies can version their API’s using distinct approaches, but these are the four common ways to version an API.
1. URI Versioning
This is the most natural and most commonly used approach. It involves the inclusion of the version number in the URL path.
https://www.example.com/api/1/productsThis strategy uses URI routing to pinpoint a particular version of the API. And since the version alters the URIs, clients can cache resources, such that when there is an update, it will be perceived as a new entry in the cache. This approach is straightforward, but it violates the principle that states that a URI should refer to a unique resource.
PROS
Most common method currently in use by APIs today.
It allows exploring different versions with just a browser. (Enables visual identification of the version being requested).
It’s easy to use!
CONS
It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version).
Just like the previous method you should try to avoid this method if you are also versioning resources.
2. Query Parameter Versioning
This approach involves including the version number as one of the query parameters.
https://www.example.com/api/products?version=1This versioning strategy is also straightforward when viewed from an implementation point of view. This approach makes it easier to switch to the newest version in case a query parameter is not specified.
PROS
This is mostly indicated for JavaScript API (CORS enabled APIs).
Just like the URI versioning allows visual identification.
Can be optional (if no parameter is specified, the last version will be provided).
CONS
If you mix resource versions with this type of API versioning, it can get very messy.
3. Custom Headers Versioning
This is a technique that allows developers to version APIs by including custom headers with version numbers included in them as an attribute.
curl -H “Accepts-version: V1.”
https://www.example.com/api/productsThis approach differs from query and URI versioning in the sense that it doesn’t add filler content to the URI.
PROS
Preserve your URIs between versions (because you do not add any version information to the URI).
Neater method than the URI versioning up next.
CONS
If you are already versioning resources with this technique, versioning the API as well can lead to a hard-to-manage configuration.
4. Content Negotiation Versioning
With this approach, developers can version a single resource representation instead of the entire API. This offers more granular control and creates a considerable footprint in the code-base.
For example:
Accept: application/vnd.example.v1+json
Accept: application/vnd.example+json;version=1.0This method also doesn’t need the implementation of URI routing rules, which are introduced by versioning via the URI path. However, this approach is less accessible when compared to URI-versioned APIs. Additionally, Content negotiation may permit you to maintain a clean set URL, but at some point, you will deal with the challenge of serving different versions of content.
PROS
You can version directly at the resource level (preserve your URIs between versions).
This is the closest to the original RESTful specification (check the references below).
CONS
Harder to test as the versions are not shown on the URL.
You will need something else than just a browser (i.e. developer tools) to explore the different versions.
They distort the HTTP headers’ purpose: clients will need to know the media type for each resource and request the same one throughout their use of your API to ensure their code continues to function normally as you push out new changes.
The Tech Platform