Modifying API responses

A typical API payload is measured in KBs rather than MBs, so few people worry about the impact of the API response on the overall performance of the app. But if you work with APIs on a daily basis, you soon reach a moment when you wish there were a way to modify the default API response. It might lead to a better performing mobile app. And a more robust code. Or a way to use the same entry for multiple platforms.

Until now, Contentful already offered the ability to hide individual fields from the JSON output, but this option required to hide fields once and for all. If you wanted to selectively hide and show fields depending on the platform, you had to retrieve them anyway and not display them, or maintain several content models to tailor entries for different clients.

The arrival of the 'select' operator makes it much easier to handle all these scenarios. The operator is a powerful query parameter you can attach to your calls to specify what content should be included in the API response. You can selectively dismiss sys properties when interested only in the content. Or skip fields when debugging the app. Combined with other parameters, this gives you more flexibility in managing and querying your content models.

We have put together this tutorial to show you how to use the operator. We will use the 'Product Catalogue' example for illustration purposes.

Choosing fields

To use the select operator, append it to your API call, with a comma separated list of fields you want, for example:

1
2
3

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

Instead of returning all fields, the default behavior, the API will now return only the fields requested - the name and price of a product - and metadata about the results.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "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

Now let's go one step further and consider the situation where you only want to fetch sys properties of the entry or, on the contrary, just want to extract entry content without bothering too much about the meta data. Only fetching one of the objects - sys or fields - contained within a request will automatically exclude the other. For example, to omit the sys object from a request, run the following:

1
2
3

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

And for fetching only sys properties:

1
2
3

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

Including the entire object will return all of its sub-fields as well. Also note that whenever using the 'select' operator, you have to specify the content type you want to query. Failing to do so will produce an error.

Note Since SDKs use sys properties to generate different types of objects, link entries, and resolve resources; it is not possible to omit sys properties when querying our API with the 'select' operator through an SDK.

Assets

You can use the operator with assets in your space in the same way. For example, to fetch just the names of assets:

1
2

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

Will return:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
  "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, however, that the 'select' operator is only supported with entries and assets collection end-points. If you attempt to use the operator with a single entry or asset endpoint, the operator will be ignored, and you will see the default response.

All APIs supported

The select operator works with the delivery, management, and preview APIs, which means you can utilize it for published entries and your drafts alike. For example:

1
2
3
4

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

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

SDK implementation

The select operator is one of the ways we plan to make working with content easier. At the moment, our Ruby and Javascript SDKs already support this feature, while other SDKs will follow the suite in the near future.