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.

There are now two EPG endpoints (instead of just one).

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

1. Call the v3 EPG endpoint
2. Call the v2 Channel endpoint
3. Calculate what to display (apply privileges from step 2 to the results from step 1)
4. 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

NB: This is a simplified process and ignores caching, which is imperitive.  Please apply all of the caching recommendations from the guide to these calls.  See below for an example of an optimised client implementation that properly caches data.

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.

Dealing with middleware cache misses

In the bottom of the right-hand side of the diagram there is a box labeled "Is requester capable of waiting for data"

Sometimes, when the nginx cache is not hit, loading of that data might take 10-15 seconds.

That’s generally too much for client so if full day epg data cannot be loaded within certain timeframe (usually 2-3 seconds) we use the the more specific EPG v3 API endpoint.

Parameters are chosen depending on the users view, but follow the guidelines that help to reduce variability and improve middleware caching.

Concrete examples

Obtain general channel program list

Call

Obtain user specific privileges for channels

Call

Mixed together

The client uses the user-specific information to filter the general EPG listing

The result is the EPG: