Modifying REST API responses

As API payload is measured in KBs rather than MBs, the impact of the API response on the overall performance of the app is neglected. But if the APIs are used excessively, the default API response starts impacting the performance of the app.

Hence, it becomes important to modify the default API response, thereby ensuring better performing mobile app and a more robust code.

The select operator is a powerful query parameter that can be attached to the calls to specify what content needs to be included in the API response.

The operator allows to selectively dismiss sys properties when interested only in the content, or skip fields while debugging the app. When Combined with other parameters, this operator provides more flexibility in managing and querying the content models.

The following sections explain how to use the operator. The Product Catalogue example is used for illustration purposes.

Choosing fields

Append the select operator in the API call, with a comma separated list of desired fields. For example:

https://cdn.contentful.com/spaces/<space_id>/entries/
    ?select=fields.productName,fields.price
    &content_type=<content_type_id>

The API returns only the fields requested - the name and price of a product along with the metadata of the results.

{
  "sys": {
    "type": "Array"
  },
  "total": 4,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "fields": {
        "productName": "Whisk Beater",
        "price": 22
      }
    },
    {
      "fields": {
        "productName": "SoSo Wall Clock",
        "price": 120
      }
    },
    {
      "fields": {
        "productName": "Hudson Wall Cup",
        "price": 11
      }
    },
    {
      "fields": {
        "productName": "Playsam Streamliner Classic Car, Espresso",
        "price": 44
      }
    }
  ]
}

Including and excluding objects

The select operator can be used to fetch sys properties of the entry or, on the contrary, just extract the entry content by fetching fields. Only fetching one of the objects - sys or fields - contained within a request automatically excludes the other. For example, to omit the sys object from a request, run the following:

https://cdn.contentful.com/spaces/<space-id>/entries/
    ?select=fields
    &content_type=<content_type_id>

And for fetching only sys properties:

https://cdn.contentful.com/spaces/<space-id>/entries/
    ?select=sys
    &content_type=<content_type_id>

Including the entire object returns all of its sub-fields as well. Ensure to specify the content type to be queried, while using the select operator. Failing to do so, results in an error.

Note: Since client libraries use sys properties to generate different types of objects, link entries, and resolve resources; it is not possible to omit sys properties when querying the API with the select operator through a client library.

Assets

The select operator can be used with the assets corresponding to a space. For example, to fetch just the names of assets:

https://cdn.contentful.com/spaces/<space-id>/assets
    ?select=fields.title

Returns:

{
  "sys": {
    "type": "Array"
  },
  "total": 7,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "fields": {
        "title": "City Street"
      }
    },
    {
      "fields": {
        "title": "Janine"
      }
    },
    {
      "fields": {
        "title": "Celebration"
      }
    },
    {
      "fields": {
        "title": "Golden Gate Bridge"
      }
    },
    {
      "fields": {
        "title": "The world on a digital screen"
      }
    },
    {
      "fields": {
        "title": "Air Baloon"
      }
    },
    {
      "fields": {
        "title": "The Flower"
      }
    }
  ]
}

Note: The select operator is only supported with entries and assets collection end-points. If the operator is used with a single entry or asset endpoint, it gets ignored, and the default response is returned.

All REST APIs supported

The select operator works with the delivery, management, and preview APIs, and can be utilized for published entries and drafts alike. For example:

https://preview.contentful.com/spaces/<space_id>/entries
    ?access_token=<access_token>
    &content_type=<content_type_id>
    &select=fields.productName

returns the same result structure as above, but for draft entries.

Client library implementation

The select operator is supported by [all the Contentful client libraries. The other client libraries would be supporting the operator soon.