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