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.
API versioning allows you to alter behavior between different clients. ... Versioning is determined by the incoming client request, and may either be based on the request URL, or based on the request headers. There are a number of valid approaches to approaching versioning.
1. Media Type Versioning (or 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.
2. Custom Headers Versioning
One of the most (mis)used methods — i.e. X-API-Version: 2.
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.
3. URI Versioning
This 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.
Example:
https://www.example.com/api/1/productsPROS
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.
4. Domain Versioning (or “Hostname Versioning”)
It’s a particular case of the URI versioning in the previous section, and it shares its pros and cons (i.e. apiv1.example.com/resource).
This approach is used when technology limitations prevent routing to the proper backend version of the API based on the URI or Accept header.
PROS
Same as in URI versioning.
Also easily route it to a completely different server.
Could be interesting if you really want to write something very different for the same resources.
CONS
Same as in URI versioning, plus users may have to change their security settings to be able to make calls to this new version.
5. (Request) Parameter Versioning
Use a parameter in the request to provide the API version being used (i.e.
GET /something/?version=0.1 HTTP/1.1
).
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.
6. Date Versioning (or “Point-in-Time Versioning,” or “Dynamic Date Versioning”)
The first time a user makes a request to the API, that point-in-time (timestamp) gets saved alongside the account data and becomes their version until they choose to manually bump it to the current version
PROS
Allows shipping new API features without changing an endpoint.
Being able to easily see which customers are using which versions of the API
CONS
It’s a bit complex to implement.
Makes traceability of what has changed more difficult (It can be confusing to understand whether the timestamp is compilation time or the timestamp when the API was released).
The Tech Platform