Stay organized with collections
Save and categorize content based on your preferences.
This document covers some techniques you can use to improve the performance of your application. In some cases, examples from other APIs or generic APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Cloud DNS API.
Compression using gzip
An easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.
In order to receive a gzip-encoded response you must do two things: Set an Accept-Encoding header, and modify your user agent to contain the string gzip. Here is an example of properly formed HTTP headers for enabling gzip compression:
Accept-Encoding:gzipUser-Agent:myprogram (gzip)
Working with partial resources
Another way to improve the performance of your API calls is by requesting 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 including 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 a generic (fictional) "Demo" API.
Simple request: This HTTP GET request omits the fields parameter and returns the full resource.
https://www.googleapis.com/demo/v1
Full resource response: The full resource data includes the following fields, along with many others that have been omitted for brevity.
Request for a partial response: The following request for this same resource uses the fields parameter to significantly reduce the amount of data returned.
Partial response: In response to the request above, the server sends back a response that contains only the kind information along with a pared-down items array that includes only HTML title and length characteristic information in each item.
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.
Exception: For API responses that use "data" wrappers, where the response is nested within a data object that looks like data: { ... }, do not include "data" in the fields specification. Including the data object with a fields specification like data/a/b causes an error. Instead, just use a fields specification like a/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=items(id,author/email) returns only the item ID and author's email for each element in the items array. You can also specify a single sub-field, where fields=items(id) is equivalent to fields=items/id.
Use wildcards in field selections, if needed.
For example: fields=items/pagemap/* selects all objects in a pagemap.
More examples of using the fields parameter
The examples below include descriptions of how the fields parameter value affects the response.
Note: As with all query parameter values, the fields parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.
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:
Examples
Effect
items
Returns all elements in the items array, including all fields in each element, but no other fields.
etag,items
Returns both the etag field and all elements in the items array.
items/title
Returns only the title field for all elements in the items 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.
context/facets/label
Returns only the label field for all members of the facets array, which is itself nested under the context object.
items/pagemap/*/title
For each element in the items array, returns only the title field (if present) of all objects that are children of pagemap.
Here are some resource-level examples:
Examples
Effect
title
Returns the title field of the requested resource.
author/uri
Returns the uri sub-field of the author object in the requested resource.
links/*/href
Returns the href field of all objects that are children of links.
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
items(title,author/uri)
Returns only the values of the title and author's uri for each element in the items 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 the user what was wrong with their fields selection (for example, "Invalid field selection a/b").
Here is the partial response example shown in the introductory section above. The request uses the fields parameter to specify which fields to return.
Note: For APIs that support query parameters for data pagination (maxResults and nextPageToken, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eEnable gzip compression by setting the \u003ccode\u003eAccept-Encoding\u003c/code\u003e header to \u003ccode\u003egzip\u003c/code\u003e and including \u003ccode\u003egzip\u003c/code\u003e in the \u003ccode\u003eUser-Agent\u003c/code\u003e string to significantly reduce bandwidth usage.\u003c/p\u003e\n"],["\u003cp\u003eRequest partial responses using the \u003ccode\u003efields\u003c/code\u003e parameter to receive only the necessary data, minimizing data transfer, parsing, and storage, thus optimizing resource use.\u003c/p\u003e\n"],["\u003cp\u003eUse a comma-separated list of field names within the \u003ccode\u003efields\u003c/code\u003e parameter to select multiple fields, nested fields, and specific sub-fields of arrays or objects using parentheses.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efields\u003c/code\u003e parameter value should be specified relative to the root of the response, whether it is a list operation returning a collection or an operation returning a single resource, and the server returns only the specified data and the enclosing parent objects.\u003c/p\u003e\n"],["\u003cp\u003eUsing the \u003ccode\u003emaxResults\u003c/code\u003e and \u003ccode\u003enextPageToken\u003c/code\u003e parameters for data pagination, where supported, will further improve performance when used in combination with partial response requests.\u003c/p\u003e\n"]]],[],null,["# Performance tips\n\nThis document covers some techniques you can use to improve the performance of your application. In some cases, examples from other APIs or generic APIs are used to illustrate the ideas presented. However, the same concepts are applicable to the Cloud DNS API.\n\nCompression using gzip\n----------------------\n\nAn easy and convenient way to reduce the bandwidth needed for each request is to enable gzip compression. Although this requires additional CPU time to uncompress the results, the trade-off with network costs usually makes it very worthwhile.\n\nIn order to receive a gzip-encoded response you must do two things: Set an `Accept-Encoding` header, and modify your user agent to contain the string `gzip`. Here is an example of properly formed HTTP headers for enabling gzip compression: \n\n```perl6\nAccept-Encoding: gzip\nUser-Agent: my program (gzip)\n```\n\nWorking with partial resources\n------------------------------\n\nAnother way to improve the performance of your API calls is by requesting 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 including network, CPU, and memory more efficiently.\n\n### Partial response\n\nBy 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.\n\nTo 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.\n\n#### Example\n\nThe following example shows the use of the `fields` parameter with a generic (fictional) \"Demo\" API.\n\n**Simple request:** This HTTP `GET` request omits the `fields` parameter and returns the full resource. \n\n```\nhttps://www.googleapis.com/demo/v1\n```\n\n**Full resource response:** The full resource data includes the following fields, along with many others that have been omitted for brevity. \n\n```text\n{\n \"kind\": \"demo\",\n ...\n \"items\": [\n {\n \"title\": \"First title\",\n \"comment\": \"First comment.\",\n \"characteristics\": {\n \"length\": \"short\",\n \"accuracy\": \"high\",\n \"followers\": [\"Jo\", \"Will\"],\n },\n \"status\": \"active\",\n ...\n },\n {\n \"title\": \"Second title\",\n \"comment\": \"Second comment.\",\n \"characteristics\": {\n \"length\": \"long\",\n \"accuracy\": \"medium\"\n \"followers\": [ ],\n },\n \"status\": \"pending\",\n ...\n },\n ...\n ]\n}\n```\n\n**Request for a partial response:** The following request for this same resource uses the `fields` parameter to significantly reduce the amount of data returned. \n\n```\nhttps://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)\n```\n\n**Partial response:** In response to the request above, the server sends back a response that contains only the kind information along with a pared-down items array that includes only HTML title and length characteristic information in each item. \n\n```\n200 OK\n``` \n\n```text\n{\n \"kind\": \"demo\",\n \"items\": [{\n \"title\": \"First title\",\n \"characteristics\": {\n \"length\": \"short\"\n }\n }, {\n \"title\": \"Second title\",\n \"characteristics\": {\n \"length\": \"long\"\n }\n },\n ...\n ]\n}\n```\n\nNote that the response is a JSON object that includes only the selected fields and their enclosing parent objects.\n\nDetails on how to format the `fields` parameter is covered next, followed by more details about what exactly gets returned in the response.\n\n#### Fields parameter syntax summary\n\nThe 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.\n\n- Use a comma-separated list to select multiple fields.\n- 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`. \n\n **Exception:** For API responses that use \"data\" wrappers, where the response is nested within a `data` object that looks like `data: { ... }`, do not include \"`data`\" in the `fields` specification. Including the data object with a fields specification like `data/a/b` causes an error. Instead, just use a `fields` specification like `a/b`.\n- Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses \"`( )`\".\n\n For example: `fields=items(id,author/email)` returns only the item ID and author's email for each element in the items array. You can also specify a single sub-field, where `fields=items(id)` is equivalent to `fields=items/id`.\n- Use wildcards in field selections, if needed. For example: `fields=items/pagemap/*` selects all objects in a pagemap.\n\n#### More examples of using the fields parameter\n\nThe examples below include descriptions of how the `fields` parameter value affects the response.\n\n**Note:** As with all query parameter values, the `fields` parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.\n\nIdentify the fields you want returned, or make field selections.\n: 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. \n\n \u003cbr /\u003e\n\n\n Here are some collection-level examples: \n\n\n \u003cbr /\u003e\n\n\n Here are some resource-level examples: \n\n\nRequest only parts of specific fields using sub-selections.\n: 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.\n\n\n\u003cbr /\u003e\n\n#### Handling partial responses\n\nAfter 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 the user what was wrong with their fields selection (for example, `\"Invalid field selection a/b\"`).\n\nHere is the partial response example shown in the [introductory section](#partial-response) above. The request uses the `fields` parameter to specify which fields to return. \n\n```\nhttps://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)\n```\n\nThe partial response looks like this: \n\n```\n200 OK\n``` \n\n```text\n{\n \"kind\": \"demo\",\n \"items\": [{\n \"title\": \"First title\",\n \"characteristics\": {\n \"length\": \"short\"\n }\n }, {\n \"title\": \"Second title\",\n \"characteristics\": {\n \"length\": \"long\"\n }\n },\n ...\n ]\n}\n```\n\n**Note:** For APIs that support query parameters for data pagination (`maxResults` and `nextPageToken`, for example), use those parameters to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with partial response might not be realized.\n\n\u003cbr /\u003e"]]