...
Easy to understand overview of versioning
...
Major divisions within the API
There are two groups of endpoints:
- Legacy
- 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.
...
| 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 has caused confusion in client developers and so everything will start at v1. |
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/)
...
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
...