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 your user's bandwidth usage bills!).

Recognising this Content 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.

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://content.api.pressassociation.io/v1/item?sort=versioncreated:desc&limit=2

Upon execution Content API returns a "full-fat" response that looks a little like the following snippet:

{
  "total": 25,
  "limit": 2,
  "offset": 0,
  "item": [
    {
      "uri": "56d467cce4b0bc4580528b65",
      "type": "composite",
      "profile": "story-enriched",
      "versioncreated": "2016-02-29T09:33:01Z",
      "urgency": 3,
      "pubstatus": "usable",
      "language": "en",
      "byline": "Carl Markham",
      "headline": "Example Sport Story 2",
      "body_text": "Awesome content here.",
      "body_html": "<p>Awesome content here.</p>",
      "subject": [
        {
          "code": "paservice:sport",
          "name": "Sport",
          "profile": "paservice",
          "scheme": "https://content.api.pressassociation.io/v1/subject",
          "rel": "partOf"
        }
      ],
      "event": [
        {
          ...
        }
      ],
      "associations": {
      	...
      },
      "links": [
        {
          ...
        }
      ]
    },
    {
      "uri": "56d4104de4b0bc4580528a9b",
      "type": "composite",
      "profile": "story-enriched",
      "versioncreated": "2016-02-29T08:33:01Z",
      "urgency": 3,
      "pubstatus": "usable",
      "language": "en",
      "byline": "Carl Markham",
      "headline": "Example Sport Story 1",
      "body_text": "Awesome content here.",
      "body_html": "<p>Awesome content here.</p>",
      "subject": [
        {
          "code": "paservice:sport",
          "name": "Sport",
          "profile": "paservice",
          "scheme": "https://content.api.pressassociation.io/v1/subject",
          "rel": "partOf"
        }
      ],
      "event": [
        {
          ...
        }
      ],
      "associations": {
      	...
      },
      "links": [
        {
          ...
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://content-uat.api.pressassociation.io/v1/item?limit=5"
    }
  ]
}

Whilst this response is great if you require all of metadata contained within the document, it's not so great if your application only requires a certain selection of fields (say uri, versioncreated, headline and subject codes) or if your users are constrained by their network and every byte counts!

With this in mind you can utilise Content 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 select the JSON fields we're interested in:

curl \
  -H "Accept: application/json" \
  -H "apikey: <API KEY>" \
  https://content.api.pressassociation.io/v1/item?sort=versioncreated:desc&limit=5&fields=total,limit,offset,item(uri,versioncreated,headline,subject/code)

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

{
  "total": 25,
  "limit": 2,
  "offset": 0,
  "item": [
    {
      "uri": "56d467cce4b0bc4580528b65",
      "versioncreated": "2016-02-29T09:33:01Z",
      "headline": "Example Sport Story 2",
      "subject": [
        {
          "code": "paservice:sport"
        }
      ]
    },
    {
      "uri": "56d4104de4b0bc4580528a9b",
      "versioncreated": "2016-02-29T08:33:01Z",
      "headline": "Example Sport Story 1",
      "subject": [
        {
          "code": "paservice:sport"
        }
      ]
    }
}

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=subject/code.
Specify field sub-selectors to request only specific sub-fields by placing expressions in parentheses "( )" after any selected field. For example: fields=item(uri) returns only the item uri.
Use wildcards in field selections, if needed. For example: *fields=item/subject/** selects all items in the subject array.