Using field masks with Google APIs for partial response
March 31, 2017
When you write applications using Google APIs (not just G Suite ones, but most Google APIs including YouTube or Google Cloud Platform APIs), it's important to be mindful of the data that’s returned in the response payloads from API calls. If you're not, your apps are likely getting back much more data than they need which can affect the performance of your apps whether on mobile or a server backend.Read More
When you write applications using Google APIs (not just G Suite ones, but most Google APIs including YouTube or Google Cloud Platform APIs), it's important to be mindful of the data that’s returned in the response payloads from API calls. If you're not, your apps are likely getting back much more data than they need which can affect the performance of your apps whether on mobile or a server backend.
That's why most Google APIs allow you to only filter the data you need from response payloads with field masks. To get you comfortable with field masks, we’ve put together a video to demonstrate their use with various Google APIs: With field masks, you can specify exactly what fields an API should return in its response payload by providing a fields or part parameter in your calls. And once the API knows what you want, it will likely spend less time assembling your response too. Here’s an example Python call to fetch your sender addresses using the Gmail API (if GMAIL is your service endpoint):
addresses = GMAIL.users().settings().sendAs().list(
userId='me'
).execute().get('sendAs')Whether you’re using a Client Library (as our Python call) or using HTTP directly with GET https://www.googleapis.com/gmail/v1/users/userId/settings/sendAs, this is the payload you get back from the API:
{
"sendAs": [{
"sendAsEmail": string,
"displayName": string,
"replyToAddress": string,
"signature": string,
"isPrimary": boolean,
"isDefault": boolean,
"treatAsAlias": boolean,
"smtpMsa": {
"host": string,
"port": integer,
"username": string,
"password": string,
"securityMode": string
},
"verificationStatus": string
}, ...]
}The sendAs array gives you everything you need to know about each of your sender addresses. Did you know you can change a user’s email signature using the Gmail API without all of the data from above? You only need one field, or at most two: sendAsEmail and perhaps the isPrimary flag. By specifying a field mask with just those names from the sendAs attribute, you can cut out all those unneeded fields. Check it out here in Python with the field mask bolded for emphasis (versus the sample code above that doesn’t filter):
addresses = GMAIL.users().settings().sendAs().list(
userId='me', fields='sendAs(sendAsEmail,isPrimary)'
).execute().get('sendAs') |
| Field masks filter our unnecessary data from Google API call responses. |
To learn more about using field masks for partial response in API payloads, check out this section of the Client Library docs. For one of the most comprehensive write-ups on both (read and update) use cases, see the guide in the Google Slides API documentation.
