Versioning your RESTful API
Sixth article in the series of “ Pragmatic decisions for your RESTful API”, this post talks about versioning your RESTful API.
Versioning your API: use URL
Your API should provide a versioning mechanism. Having no versioning mechanism for your API means that you will not be able to change the shape of your resources without possibly breaking client implementations.
There are 3 possibilities for API versioning:
- versioning via the URL: for example
GET /v2/users - versioning in query parameters: for example
GET /users?version=2 - versioning via HTTP headers, for example via the Accept header:
Accept: application/json; version=2
Versioning via query parameters is definitely not the recommended way of doing it, because you are mixing query parameters (ie fields, sort, offset etc…) with control parameters (version).
Deciding between versioning via HTTP headers and via the URL is harder however, as there are pros and cons to each of them (pros are in bold).
Versioning via URL:
- Easy to use and test
- Strictly speaking, does not respect REST standards (because additional elements are added in the URL which are not part of resource path in REST meaning)
- Fully compatible with all tools
- Multiple resource addresses depending on versions
Versioning via HTTP Headers:
- Harder to test
- Respects REST standards
- If using a custom header, might not be compatible with all tools
- One resource address for all versions
Even though versioning via URL does not fully respect REST meanings and standards, this is still what I recommend, as it is the easiest method to use and test.
More importantly however, small changes might not require version changes. For example, if you just add attributes to your resources, there is no need to create a new version of your API (since your clients will be able to parse your resources even with the new attribute). Only change version number if you really need to.
If you want to read all of the articles of the series “ Pragmatic decisions for your RESTful API”, you can start here. The next article will focus on rate limiting.
This series of articles about Restful API design is also available as an eBook on Amazon, if you need it in a handy format.
Originally published at https://www.gvj-web.com on March 27, 2018.
