General notes

Endpoints are versioned independently. For example, if you're using EPG v3 you do not have to use Channel v3.

If you migrate one endpoint to a new endpoint major version you do not need to update the rest of the application.

We have legacy API's and RESTful API's.

Easy to understand overview of versioning

Major divisions within the API

There are two groups of endpoints:

Legacy - v1 to v3
REST

Our new API philosophy is much more strict on adhering to RESTful principals and to versioning.

Endpoint versions

The general principal is that any particular endpoint is versioned independently of any others.

Each endpoint should begin at v1.

Therefore all of our new REST endpoints are going to begin at "v1".

We had been referring to the new REST endpoints as "v4" to try and prevent the situation where an upgrade path results in a version downgrade. For example, upgrading v3 EPG to v1 Program Metadata. This is an inconsistency in our versioning philosophy. We are rather using v1 as the first version for every endpoint, regardless of whether it is legacy or REST.

How upgrading and migration works with respect to versioning

You can upgrade within legacy (for example from EPG v2 to EPG v3) or migrate from legacy to REST (for example by replacing EPG with calls to the three REST endpoints).

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 MUST NOT include the minor portion (e.g.: /api/v2.1/)

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")

Each endpoint function MUST have an annotation for @since that is updated with the ticket that caused you to modify the function

Versions in use

Please see Endpoints in production use

AminoTV API

AminoTV API versioning