API Versioning

The HTTP API exposed by the service will be consumed by clients, like a Javascript client.

The HTTP API is subject to changes. It follows the Cliquet Protocol.

When the HTTP API is changed, its version is incremented. The HTTP API version follows a Semantic Versioning pattern and uses this rule to be incremented:

  1. any change to the HTTP API that is backward compatible increments the MINOR number, and the modification in the documentation should reflect this with a header like “Added in 1.x”.
  2. any change to the HTTP API that is backward incompatible increments the MAJOR number, and the differences are summarized at the begining of the documentation, a new document for that MAJOR version is created.


We’re not using the PATCH level of Semantic Versioning, since bug fixes have no impact on the exposed HTTP API; if they do MINOR or MAJOR should be incremented.

We want to avoid MAJOR changes as much as possible in the future, and stick with 1.x as long as we can.

A client that interacts with the service can query the server to know what is its HTTP API version. This is done with a query on the root view, as described in the root API description.

If a client relies on a feature that was introduced at a particular version, it should check that the server implements the minimal required version.

The JSON response body contains an http_api_version key which value is the MAJOR.MINOR version.