Display & Video 360 API v3 has sunset. Migrate to v4.

Improve Performance

AI-generated Key Takeaways

Improve API performance by requesting only the portion of data needed, known as a partial response.
Use the fields request parameter with any request that returns response data to specify desired fields for a partial response.
The fields parameter syntax uses a comma-separated list for multiple fields and parentheses for sub-selections.
A valid partial response request returns an HTTP 200 OK status code with the requested data, while an invalid one returns an HTTP 400 Bad Request.

This document covers some techniques you can use to improve the performance of your application. In some cases, examples from other implemented APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Display & Video 360 API.

Working with partial resources

Another way to improve the performance of your API calls is to request only the portion of the data that you're interested in. This lets your application avoid transferring, parsing, and storing unneeded fields, so it can use resources such as network, CPU, and memory more efficiently.

Partial response

By default, the server sends back the full representation of a resource after processing requests. For better performance, you can ask the server to send only the fields you really need and get a partial response instead.

To request a partial response, use the fields request parameter to specify the fields you want returned. You can use this parameter with any request that returns response data.

Example

The following example shows the use of the fields parameter with the Display & Video 360 API.

Simple request: This HTTP GET request omits the fields parameter and returns the full resource.

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1

Full resource response: The full resource data includes the following fields, along with many others that have been omitted for brevity.

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

Request for a partial response: The following request for this same resource uses the fields parameter to significantly reduce the amount of data returned.

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

Partial response: In response to the request above, the server sends back a response that contains a pared-down advertisers array that includes only the advertiser ID, display name, and partner ID property of each advertiser, if present.

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

Note that the response is a JSON object that includes only the selected fields and their enclosing parent objects.

Details on how to format the fields parameter is covered next, followed by more details about what exactly gets returned in the response.

Fields parameter syntax summary

The format of the fields request parameter value is loosely based on XPath syntax. The supported syntax is summarized below, and additional examples are provided in the following section.

Use a comma-separated list to select multiple fields.
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.
Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses "( )".

For example: fields=advertisers(advertiserId,generalConfig/domainUrl) returns only the advertiser ID and domain URL for each element in the advertisers array. You can also specify a single sub-field, where fields=advertisers(advertiserId) is equivalent to fields=advertisers/advertiserId.

More examples of using the fields parameter

The examples below include descriptions of how the fields parameter value affects the response.

Identify the fields you want returned, or make field selections.

The fields request parameter value is a comma-separated list of fields, and each field is specified relative to the root of the response. Thus, if you are performing a list operation, the response is a collection, and it generally includes an array of resources. If you are performing an operation that returns a single resource, fields are specified relative to that resource. If the field you select is (or is part of) an array, the server returns the selected portion of all elements in the array.

Here are some collection-level examples:

Example	Effect
`advertisers`	Returns all elements in the `advertisers` array, including all fields in each element, but no other fields.
`advertisers,nextPageToken`	Returns both the `nextPageToken` field and all elements in the `advertisers` array.
`advertisers/advertiserId`	Returns only the `advertiserId` for all elements in the `advertisers` array. Whenever a nested field is returned, the response includes the enclosing parent objects. The parent fields do not include any other child fields unless they are also selected explicitly.
`advertisers/generalConfig/domainUrl`	Returns the `domainUrl` field for the `generalConfig` object, which itself is nested under the `advertisers` array.

Here are some resource-level examples:

Example	Effect
`advertiserId`	Returns the `advertiserId` field of the requested resource.
`generalConfig/domainUrl`	Returns the `domainUrl` field for the `generalConfig` object in the requested resource.

Request only parts of specific fields using sub-selections.

By default, if your request specifies particular fields, the server returns the objects or array elements in their entirety. You can specify a response that includes only certain sub-fields. You do this using "( )" sub-selection syntax, as in the example below.

Example	Effect
`advertisers(advertiserId,generalConfig/domainUrl)`	Returns only the values of `advertiserId` and generalConfig `domainUrl` for each element in the `advertisers` array.

Handling partial responses

After a server processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code, along with the requested data. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code, along with an error message telling you what was wrong with the fields selection (for example, "Invalid field selection a/b").