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
| Tip |
|---|
| 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".
| Info |
|---|
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 SHOULD 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 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