Migrating to the new PlayableStream format endpoints
Using the old endpoint
Currently the client will call our "play" endpoint which returns an JSON object containing the URL where the stream is available and the DRM information required to play it.
Using the new endpoint
Our new endpoint PlayableStream related to Channel (live) returns similar information, but is more detailed.
The chief differences to note are:
- The startover parameter is renamed to "restart_at_beginning"
- The following parameters are no longer required or supported:
- service
- ajax
- stream_type
- The API will return a number of different stream_types and let the client pick which one to display
- The "suggested_devices" key in the response is non-normative and is just a suggestion
| language | js |
|---|---|
| theme | Midnight |
| title | Response structure |
| linenumbers | true |
| collapse | true |
Summary of version numbers and their lifecycle
| Version | Comment | Usage notes |
|---|---|---|
| 1.x | Deprecated endpoints | Do not use |
| 2.x | Most of the endpoints are still current in active support. | Check the endpoint lifecycle here before using it |
| 3.0 and 3.1 | These are limited to the EPG endpoints. These endpoints follow the "old" philosophy. | At time of writing (Q3 2019) we don't recommend upgrading from v2 to v3 because v4 is soon to be released. |
| 4.x | These are new endpoints following our "new" philosophy that improves REST compliance. | These are the endpoints we would prefer you to use. |
Introduction to V4
The migration documentation for each section will explain the differences in more detail so this is just a high level overview of "what's new".
V4 is an ongoing redesign of our API to make it more REST compliant. More of the new endpoints will be rolled out as features and improvements are deployed.
You will notice that endpoints are focused on specific resources, and we limit the relationships that can be fetched.
This reduces parameter variability and the amount of data that must be pulled from the database; As a result the response should be quicker to generate and easier to cache.
You'll notice that the responses adhere to the JSON API 1.0 standard (http://jsonapi.org/) and wherever possible the recommendations have been accepted as well.