REST API Versioning

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.

e.g. https://api.foursquare.com/v2/venues/40a55d80f964a52020f31ee3/tips

 

Pros:

- Ability to version specific resource branches.
- Semantically dev friendly
- Bookmarking is tightly coupled
- Enables version navigation/discovery

Cons:

- 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.

MyAPIVersionRequest-Header: 2

d) Query Parameter Versioning

Add the version as part of the Query Parameters. For e.g. Netflix uses this in their API’s

http://api.netflix.com/catalog/titles/series/70023522?v=1.5

or eBay

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.

 

References:

http://blog.restcase.com/restful-api-versioning-insights/

http://www.django-rest-framework.org/api-guide/versioning/#versioning-with-rest-framework

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s