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 Android Over The Air 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: gzip User-Agent: my program (gzip)
Working with partial resources
Another 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
fieldsrequest parameter). - Patch: An update request where you send only the fields you want to change (use the
PATCHHTTP 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
Patch (partial update)
You can also avoid sending unnecessary data when modifying resources. To send updated data only for the specific fields that you’re changing, use the HTTP PATCH verb. The patch semantics described in this document are different (and simpler) than they were for the older, GData implementation of partial update.
The short example below shows how using patch minimizes the data you need to send to make a small update.
Example
Handling the response to a patch
After processing a valid patch request, the API returns a 200 OK HTTP response code along with the complete representation of the modified resource. If ETags are used by the API, the server updates ETag values when it successfully processes a patch request, just as it does with PUT.
The patch request returns the entire resource representation unless you use the fields parameter to reduce the amount of data it returns.
If a patch request results in a new resource state that is syntactically or semantically invalid, the server returns a 400 Bad Request or 422 Unprocessable Entity HTTP status code, and the resource state remains unchanged. For example, if you attempt to delete the value for a required field, the server returns an error.
Alternate notation when PATCH HTTP verb is not supported
If your firewall does not allow HTTP PATCH requests, then do an HTTP POST request and set the override header to PATCH, as shown below:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Difference between patch and update
In practice, when you send data for an update request that uses the HTTP PUT verb, you only need to send those fields which are either required or optional; if you send values for fields that are set by the server, they are ignored. Although this might seem like another way to do a partial update, this approach has some limitations. With updates that use the HTTP PUT verb, the request fails if you don't supply required parameters, and it clears previously set data if you don't supply optional parameters.
It's much safer to use patch for this reason. You only supply data for the fields you want to change; fields that you omit are not cleared. The only exception to this rule occurs with repeating elements or arrays: If you omit all of them, they stay just as they are; if you provide any of them, the whole set is replaced with the set that you provide.