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