Skip to content

Customize API Responses

All of the APIs and endpoints in this document allow the caller to specify exactly what fields that want returned from the endpoint. This is accomplished by using a special query parameter named fields. For more detail please refer cl-partial-response repo.

This has several benefits:

  • Decrease network I/O, sometimes significantly
  • Ensuring that only fields that you are prepared to parse are returned, especially in the case of new API versions adding new fields that existing client code is not aware of.
  • The server code may use the fields parameter to optimize loading objects from the underlying data stores such that objects which are not being returned are not loaded, thereby decreasing latency.

In all APIs that accept the fields parameter, it is optional and if it is not specified, all fields are returned. However, it is strongly recommended that the field parameter be used in production due to improved performance.

Limitations: currently no supported syntax to exclude fields. If fields are needed, please define those fields explicitly.

Format

The fields parameter takes the form of a comma-separated list of top-level JSON fields, with additional levels specified within parentheses. An asterisk implies all fields at a certain level. For example:

  • fields=foo
  • fields=foo,bar
  • fields=foo,bar(baz, foo(bar))
  • fields=foo,bar(*)

Examples

For this section, refer to the AdList object for the full JSON that is being filtered.

Note that examples don't include other required parameters for the API and are not URL-encoded. In addition, the shape of the response may not match the actual response of the API. These are just here to demonstrate the fields parameter.

Specific fields and child fields

Request

1
GET /ads?fields=ads(status,offerAmount,creatives(impressionToken,shortPreMessage))

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
   "ads":[
      {
         "status":3,
         "offerAmount":"12",
         "creatives":[
            {
               "impressionToken":"72851904b1ed4c148802622fac1656e3",
               "shortPreMessage":"Save 99.9% at Bob's"
            }
         ]
      },
      {
         "status":3,
         "offerAmount":"20",
         "creatives":[
            {
               "impressionToken":"afdagwe234254365465765756sfsfwe",
               "shortPreMessage":"Save 99.9% at Bob's"
            }
         ]
      }
   ]
}

Specific child field and all of its fields

Request

1
GET /ads?fields=ads(creatives)

Response

 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
46
47
{
   "ads":[
      {
         "creatives":[
            {
               "impressionToken":"string",
               "shortPreMessage":"string",
               "preMessage":"string",
               "postMessage":"string",
               "thankYouMessage":"string",
               "images":[
                  {

                  }
               ],
               "logo":{
                  "url":"string",
                  "text":"string"
               },
               "beacons":{
                  "preMessageImpression":"http://example.com/foo",
                  "postMessageImpression":"http://example.com/bar"
               }
            },
            {
               "impressionToken":"string",
               "shortPreMessage":"string",
               "preMessage":"string",
               "postMessage":"string",
               "thankYouMessage":"string",
               "images":[
                  {
                     "logo":{
                        "url":"string",
                        "text":"string"
                     },
                     "beacons":{
                        "preMessageImpression":"http://example.com/foo",
                        "postMessageImpression":"http://example.com/bar"
                     }
                  }
               ]
            }
         ]
      }
   ]
}

Single root field

Request

1
GET /ads?fields=categories

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
   "categories":[
      {
         "name":"Shopping",
         "id":"1",
         "subcategories":[
            null
         ],
         "adIds":[
            "123"
         ]
      }
   ]
}