Working with partial resources
A simple way to improve the performance of your API calls is by sending and
receiving 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.
There are two types of partial requests:
Partial response:
A request where you specify which fields to include in the response (use the fields request parameter).
Patch: An update request where you send only the fields you want to change (use the PATCH HTTP verb).
More details on making partial requests are provided in the following sections.
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.
Note that the fields parameter only affects the response data; it does not
affect the data that you need to send, if any. To reduce the amount of data
you send when modifying resources, use a patch request.
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?key=YOUR-API-KEY
Full resource response: The full resource data includes the following
fields, along with many others that have been omitted for brevity.
{
"kind": "demo",
...
"items": [
{
"title": "First title",
"comment": "First comment.",
"characteristics": {
"length": "short",
"accuracy": "high",
"followers": ["Jo", "Will"],
},
"status": "active",
...
},
{
"title": "Second title",
"comment": "Second comment.",
"characteristics": {
"length": "long",
"accuracy": "medium"
"followers": [ ],
},
"status": "pending",
...
},
...
]
}
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.
Response status : 200 OK
