Introduction
This document aims to briefly explain the process of migrating to the v3 EPG endpoints.
The migration will involve changing client logic and involves more than simply changing endpoints.
NB: Please see API guidelines for app development#EPG for guidelines on the new functionality. This document does not repeat information contained there
Explanation of the differences between the versions
The chief difference in the middleware between v2 and v3 lies in improvements in our caching strategy.
One endpoint is cheap because it can be publicly cached and the other is more expensive because it is unique to a particular user.
The impact on clients is that instead of calling a single endpoint to obtain EPG it is required to make a call to at least two endpoints.
- Use the publicly cacheable (cheap) endpoint to display a general EPG
- Use the privately cacheable (expensive) endpoint to discover the users individual privileges (e.g.: record, catchup, restart) for a particular channel
- Use the privately cacheable (expensive) Channel endpoint to get privileges for all channels at once
Note: There are three endpoints in this list. Typically the client will make a call to the first one and then to either of the following two (depending on use case).
How to display EPG
- Call the v3 EPG endpoint
- Call the v2 Channel endpoint
- Calculate what to display (apply privileges from step 2 to the results from step 1)
- Display it
Step 3 is the probably largest change for the migration process as it involves creating client logic where previously you didn't need any
Model client implementation
This diagram is taken from Caching of EPG data and is an optimized implementation of the EPG call.
It shows how the cache is populated and when calls need to be made to the API.
Note that there are two caches on the client, with differing expiry times.
It is combined with a call to the v2 Channel endpoint to display user specific info.
Concrete examples
Obtain general channel program list
Call
| Method | URL | Purpose | Notes |
|---|---|---|---|
| GET | https://tv.dna.fi/api/v3/epg?service=dnaclient&pg=1&st=1535576400&et=1535662800 | Obtain a list of the programs showing on all channels | The time window is 86400 seconds and this hits our Nginx cache so is extremely cheap for us. In the model client implementation the result is stored in local storage. |
Obtain user specific privileges for channels
Call
| Method | URL | Purpose | Notes |
|---|---|---|---|
| GET | https://tv.dna.fi/api/user/andy.beak@aminocom.com/channel?service=dnaclient&include=liveservice%2Crecordingservice%2Ccategories&lang=fi&sort=rank__asc&stream_protection=all&output=normal | List channels and find user specific privileges for each | Please cache the response for a few minutes |
Mixed together
The client uses the user-specific information to filter the general EPG listing
The result is the EPG:
