Customer champions

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)

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 formats 

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 MUST be documented on this Confluence page ("Move API version tracking")

Versions in use

Please see Endpoints in production use