Partial Response

When building any networked application we understand how important it is to keep the data transferred over the network to an absolute minimum. This is especially important when building mobile and web applications where increased network overhead can seriously impact user experience (and also bandwidth usage bills!).

Recognising this, the TV API fully supports partial response when using the JSON media type, meaning that you can determine the exact fields you'd like returned in your API responses.
s
In order to return a partial representation of a response use the fields query parameter. Let's take a look at an example of how partial response could be used using this parameter.

To demonstrate how this can be used let's make the following request to return the 2 latest items:

curl \
  -H "Accept: application/json" \
  -H "apikey: <API KEY>" \
  https://tv.api.pressassociation.io/v2/schedule?channelId=2a548fcc-55e9-561d-9a77-f485fb69dad1&start=2019-04-18

Upon execution, the TV API returns a "full-fat" response:

{
    "hasNext": false,
    "total": 30,
    "item": [
        {
            "id": "c20e7779-77d5-449a-b8de-2e72c6d692f3",
            "title": "Weather for the Week Ahead",
            "dateTime": "2019-04-18T00:05:00.000Z",
            "duration": 5,
            "certification": {},
            "meta": {},
            "attribute": [
                "subtitles",
                "16x9",
                "hd"
            ],
            "summary": {},
            "asset": {
                "id": "61ad65c9-c3a7-596f-812d-0260a2551f5d",
                "type": "episode",
                "title": "17/04/2019",
                "certification": {},
                "meta": {},
                "category": [
                    {
                        "code": "news-current-affairs",
                        "name": "News/Current Affairs"
                    },
                    {
                        "code": "news-current-affairs:weather",
                        "name": "Weather",
                        "dvb": "2F03"
                    }
                ],
                "attribute": [],
                "summary": {},
                "contributor": [],
                "media": [],
                "related": [
                    {
                        "type": "series",
                        "id": "6953ebec-f877-5881-8dae-33329dc7dab2",
                        "title": "Weather for the Week Ahead",
                        "media": [
                            {
                                "kind": "image:asset",
                                "copyright": "BBC iPlayer",
                                "rendition": {
                                    "default": {
                                        "href": "https://tv.assets.pressassociation.io/f6edde30-7a58-57f7-a186-1c96bea11b9d.jpg"
                                    }
                                }
                            }
                        ]
                    }
                ],
                "link": []
            }
        }        
    ]
    ...
}

Whilst this response is great if you require all of the metadata contained within the document, it's not great if your application only requires a certain selection of fields (say id, title, dateTime and duration) or if your users are constrained by their network.

With this in mind, you can utilise the TV API's partial response feature to trim the response payload down to your exact requirements.

Let's try the same request but this time only selecting the JSON fields we're interested in:

curl \
  -H "Accept: application/json" \
  -H "apikey: <API KEY>" \
	https://tv.api.pressassociation.io/v2/schedule?channelId=2a548fcc-55e9-561d-9a77-f485fb69dad1&start=2019-04-16&fields=item(id,title,dateTime,duration)

When executing this request, we are now returned only the fields we're interested in, meaning a considerably smaller payload for a client application to process. The subsequent response:

{
    "item": [
        {
            "id": "c67ae8a7-87a8-40c7-9416-86f1e3ecdf1d",
            "title": "Breakfast",
            "dateTime": "2019-04-16T05:00:00.000Z",
            "duration": 195
        }
        ...
      ]
}

The format of the fields request parameter value is loosely based on XPath syntax. Additional examples are provided in the following section:

Use a comma-separated list to select multiple fields (e.g. total,limit,offset).
Use a/b to select a field b that is nested within field a; use a/b/c to select a field c nested within b. For example:?fields=prize/value.
Specify field sub-selectors to request only specific sub-fields by placing expressions in parentheses "( )" after any selected field. For example: ?fields=items(id) returns only the item id.
Use wildcards in field selections, if needed. For example: ?fields=meta/* selects all items in the meta object.