General notes
Endpoints are versioned independently. For example, if you're using EPG v3 you do not have to use Channel v3.
...
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:
...
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. |
...
| 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
...
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 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 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