1. Timothy Corbett-Clark
  2. rest-api-blueprint


Clone wiki

rest-api-blueprint / ApiVersioning

API versioning


This area is rife with strong conflicting opinions. For example:

Establishing a home document for the API is also relevant:


Perhaps the opinions can be usefully categorised into the RESTful purists who think in terms of resources, unchanging identities, verbs, and links etc, and the community of programmers today who think in terms of a set of addresses, behaviours, changing semantics, and users with old browsers/tools. In short: some people focus on "REST" and others focus on "API". We should not be surprised therefore if the notion of a "REST API" results in some conflict and debate.

It boils down to one of two approaches:

  1. Include the version information somewhere in an HTTP header, most obviously using the mimetype in the Accept and Content-Type headers
  2. Include the version information somewhere in the URL

This is how I see it:

  1. Versioning is more than the data format. We want to version the whole API, which is a collection of things including resources, data formats, underlying behaviour, and failure handling.
  2. New HTTP headers can be stripped by proxies.
  3. Custom mimetypes are a hastle (see comments on Mime Types).
  4. Whatever we do should be obvious and convenient given today's tools and expectations.
  5. If we can ensure that clients always run the same or older version of the API against the servers (i.e. no future compability challenges) then the code behind a given API can change so long as it remains compatible with older clients. This is simply versioning to the major part of a major.minor.maintenance scheme (see http://semver.org/).

What do other APIs do?

Use URL:

  1. Amazon cloud - version indicated with a date in the URL.
  2. Bitbucket - version indicated by a 1.0 in the URL.
  3. Dropbox - version indicated by a 0 or 1 in the URL.
  4. Salesforce REST API cheatsheet (pdf) - version indicated by a vNN.N in the URL.
  5. Read-the-docs - version indicated by a v1 in the URL.

Use Header:

  1. Github - uses e.g. Accept: application/vnd.github.v3+json.
  2. Sun cloud - uses e.g. new Header X-Compute-Client-Specification-Version: 0.1 with more version information in the returned JSON.


  1. Huddle - no version information visible (and the rest of the API looks well constructed).


Include the major version number in the URL e.g. http://api.example.com/v1/blah. The API can change without clocking this number, but only if it is backwards compatible.

Strictly speaking, that means it is not a true REST API, but most people will use that term so why call it anything else?

To discover the available versions: GET to http://api.example.com.