...

How to version the API

Versions and URLs

A version MUST include a major and minor portion, for example: 2.1 

The endpoint url MUST include at least the major version (e.g.: /api/v2) and

The endpoint url MAY include the minor portion (e.g.: /api/v2.1/) but this should not be required

Each endpoint MAY have it's own version (and doesn't have to share a version with a group of endpoints, e.g.: recordings/search can be different version from recordings/play)

Changing versions

All changes to API code MUST be regression tested by the implementor against all projects

The version of the API MUST change if there is any change to the endpoint request or response formatsformats 

All minor version changes MUST be regression tested by the implementor against all projects

All minor versions of the API MUST be backwards compatible within the major version (this allows the same url to be used for all minor versions within the major version, like /v2/)

The major version of the API MUST change if there is any breaking change to the API (this prevents forcing breaking changes on clients)The version of the API MAY change by a minor version instead of a major version if the change to the interface is tested to be backwards compatible

The version of the API MUST change by a major version if the change to the interface is found to be a breaking change 

The version of the API SHOULD NOT change if there is a change to the implementation that does not affect the interface exposed to clients

The effect of this is that all the minor versions within a major version MUST be backwards compatible

Documenting

Each endpoint MUST have a version that is documented in the Jenkins generated documentation

Each endpoint MAY have it's own version (and doesn't have to share a version with a group of endpoints, e.g.: recordings/search can be different version from recordings/play MUST be documented on this Confluence page ("Move API version tracking")

Version usage

...