Versioning Strategies
Last updated
Last updated
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.
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
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.
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.
Real World Example
