Versioning Strategies

Any RESTful API (internal or public-facing) that has been around the block for a long period of time will eventually experience some sort of version change. API versioning essentially boils down to supporting forwards and backwards compatibility as well as supporting multiple different API versions.

API versioning was never an issue for me since I had only worked for small to medium sized businesses in the beginning of my career. However, as I progressed further in my career and gained more experience working with older systems, the concept of versioning became more apparent. The concept of being able to label versions so that the client consuming your RESTful API can easily comprehend it is an important feature of your API.

In this section we will talk about the 4 main versioning strategies that can be applied when building your RESTful API. There is no real "correct" or "best" approach, but rather pros and cons to each of them.

URI

This is by far the most common and most popular method of versioning. Not only do the majority of developers already do this in their code bases, most of the large tech companies use this method as well. It is extremely easy for both developers developing the API and for clients consuming the API. It is a very visible, obvious, direct, and pragmatic.

However, the only problem with this approach is... well... it isn't considered RESTful (by the man himself).

Examples

https://api.website.com/v1/resources

https://www.website.com/api/v1/resources

Real World Examples

Stripe: https://stripe.com/docs/api/versioning

PayPal: https://developer.paypal.com/docs/api/overview/#make-rest-api-calls

Twitter: https://developer.twitter.com/en/docs/twitter-api/versioning

Hostname

The usage of hostnames as versioning is quite similar to using the URI. It's easy to understand from the client's perspective. There's quite a clear separation of different versions via the subdomains. The difficult part might be that one has to use DNS in order to split and manage versions over multiple servers, that could be both good and bad depending on the situation.

Examples

https://api-v1.website.com/resources

https://api-v2.website.com/resources

Real World Example

League of legends: https://developer.riotgames.com/docs/lol

I've also seen a lot of the internal APIs built by companies that I worked at use this approach. Typically, different versions are used within the subdomains as well as a way to split up development, staging, and production environments.

Query Parameter

Using the optional query parameter is yet another popular method of versioning. It technically does follow REST since it is an optional parameter, which means it does not interfere with any concrete resources. However, I find that if not specified explicitly in the documentation, it's quite easy for developers to forget or to even know that there is a custom parameter required for a different version.

Examples

https://www.website.com/api/resources?version=1.0

https://www.website.com/api/resources?v=10-01-2049

Real World Example

Google: https://developers.google.com/gdata/docs/developers-guide?csw=1#updating-a-raw-http-client

An API that expects a consumer to communicate its version preference through HTTP headers normally defines a custom HTTP header. If you take this approach, your custom header should be "x-SOMETHING". I actually quite like this method, but the only problem with it is that some developers (mainly junior ones) can get confused if they do not know about headers very well.

Example

Making a GET request with a custom x-version header.

GET /resources HTTP/1.1
Host: api.website.com
x-version: 1.0

Real World Example

Microsoft Azure: https://docs.microsoft.com/en-us/rest/api/storageservices/Versioning-for-the-Azure-Storage-Services?redirectedfrom=MSDN#specifying-service-versions-in-requests

Last updated