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/v3/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/v3/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 fieldb
that is nested within fielda
; usea/b/c
to select a fieldc
nested withinb
.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, wherefields=advertisers(advertiserId)
is equivalent tofields=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 alist
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 theadvertisers
array.advertisers/advertiserId
Returns only the advertiserId
for all elements in theadvertisers
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 thegeneralConfig
object, which itself is nested under theadvertisers
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 thegeneralConfig
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 generalConfigdomainUrl
for each element in theadvertisers
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"
).