Use the supported API versions

Our API's Clients SHOULD use the version of the API that is currently supported

Reduce parameter variability

Clients SHOULD try to limit the variability of the parameters they pass to the API, for example by:

• Rounding starting and ending timestamps to the closest hour (for example quarter past ten should become ten o'clock exactly),
• Filtering results in the client rather than specifying exact time parameters,
• Using the same pagination values for collections if you fetch them in different places (for example don't paginate by 200 in one place and then 400 in another),

Clients SHOULD use fixed block lengths for durations, for example by:

• Using fixed length blocks of time like 1h, 2h, 4h, 6h, 24h
  
• Making sure that the duration (as measured by  the difference between "end time" and "start time") is always one of these block lengths
• We prefer larger block lengths rather than smaller lengths

In other words, clients SHOULD filter the results they need out of the block length rather than asking for specific windows of time (that we cannot cache)

Avoid needless calls

Clients SHOULD NOT make calls unless the data are needed, for example:

• Changing device orientation should not require a duplicate POST to the playback url
• Do not call endpoints to hydrate collections unless you need the data (avoid greedy loading of detail information)
• Avoid duplicating calls (for example if an endpoint is called on login then do not call it again unless the cache has expired)
• Load list data on demand rather than loading an entire list at a time (see HTML5 on-demand data loading)

Clients MAY call the server time endpoint but SHOULD minimize these calls

Limit result size

Clients MUST avoid asking for more information than they need, for example by:

• Setting a pagination limit (or max_items) of 200 to 400
• When providing search parameters (for example in calls to EPG) list the title first and the description second,

Note:  In the future API MAY silently reduce pagination sizes on requests.  This behaviour is preferred to the API throwing a "413 Payload Too Large" error in response to requests with an unreasonably large pagination size.

Manage Cache

Clients SHOULD respect the cache-control headers that are emitted by the API

Clients SHOULD make use of appropriate client side storage solutions for caching

Clients SHOULD make efforts to cache EPG data, for example by fetching a full day at a time and storing that result locally

Clients SHOULD make efforts to cache recording data for seven days at a time