Handling message versioning in REST

All services change over time, mainly because of new business requirements. More often than not, this includes changes to the entity structure.

Following are several options available to handle entity versioning:

• URL versioning: Here the URL determines the version that is to be returned. This option seems to be the most common method used, although this goes against the RESTful nature of the URL, which expresses the resource. Although this provides a very simple mechanism for versioning, it requires the server to maintain multiple versions of the URL even though you are fetching the same information.

  HTTP GET: https://my_rest_service.com/api/v2/account/10043

• Query string versioning: This option appends the required version number to the query string. The disadvantage of using this method is that some browsers and Internet Service Providers (ISPs) do not cache response messages when the request URL includes a query string.

  HTTP GET:

  https://my_rest_service.com/api/account/10043?version=2

• Custom header versioning: This option adds a custom property to the request header and requires the client to append the custom property with each server request.

  HTTP GET: https://my_rest_service.com/api/account/10043

  X-api-version = 2

  Note

  Normally, custom header properties are prefixed with X, although there are no standards on the correct naming convention.

• Media type versioning: This method is more in line with the REST specifications. The version is specified in the accept header property of request headers.

  HTTP GET:

  https://my_rest_service.com/api/account/10043

• Accept: application/vnd. my_rest_service -v2.0+json, application/vnd.account+json

  The appended second part /vnd.account+json of the my_rest_service accept header informs the service to return any version if version 2.0 cannot be found. Also the +json keyword informs the server to return the response as JSON.

  To request different versions of the account object, set the accept header as follows:

  1.0: vnd. my_rest_service -v1.0+json
  1.1: vnd. my_rest_service -v1.1+json
  2.0: vnd. my_rest_service -v2.0+json

Unfortunately, there is no silver bullet to resolve which option to use as there are pros and cons for each one. The custom header and media type versioning strategy, require the server to examine these properties for every request in order to determine which entity version to return. The client also needs to configure the header properties with each request. The other method of using URL versioning or query string versioning is cache friendly to browsers and ISPs. However, this is not the purest form of creating a RESTful API.

The bottom line comes down to who will be consuming your services and what will be their preferred method. Most of the early adopters of REST-style services used the URL versioning strategy.