a) URI Versioning
Add versions in the URI path. Ideally, the URI should represent only the resources. But this is a way of versioning which is used by many clients.
GET /v1/bookings/ HTTP/1.1 Host: example.com Accept: application/json
Any change to the API’s is followed by a new version, which might break the hyperlinks. But it is easy and is visible so there is no way one can go wrong with this method of versioning. Foursquare API’s are URI versioned.
- Ability to version specific resource branches. - Semantically dev friendly - Bookmarking is tightly coupled - Enables version navigation/discovery
- New versions change resource name and location - Complex proliferation of URI aliases - Bookmarking is tightly coupled (see pros!) - Enables version navigation/discovery (see pros!) - Can't use URI easily to compare identity - New versions break existing hyperlinks
b) Accept Header Versioning
Provide the versioning as part of the accept-header while passing the request to the server.
One way is
GET /bookings/ HTTP/1.1 Host: example.com Accept: application/json; version=1.0
Another way is
Accept: application/vnd.myapi.v2 + json with a custom resource type (Oracle has this for their DBaaS services)
They are harder to test and it is hidden so the clients might not know that they have to update it for the next version and miss it entirely. But this is recommended by many as a best practice.
c) Custom Request Header
Not a good option because it could be skipped by the routers while sending the requests because this is not a common request header. So it is not recommended. It is also hidden another problem.
It is usually done by adding a totally new request header like this.
d) Query Parameter Versioning
Add the version as part of the Query Parameters. For e.g. Netflix uses this in their API’s
http://open.api.ebay.com/shopping? callname=FindPopularItems &appid=YourAppIDHere &version=517 &siteid=0 &responseencoding=NV
Again, it is difficult if you want to update to a new version. We need to modify the API calls and also the existing hyperlinks might break (when they finally deprecate the version) and we have to keep parsing the query parameter and re-route the request based on the version. But at least the client knows which version of the API’s needs to be used in their code.
There is no single defined way of versioning of the RESTful API’s. Different services use different types. It depends on how the design is done.