Partial Responses

One of the nice to have feature in any REST API is partial responses. With the help of partial responses, you can request only those fields which will be used. By only requesting information that it will actually use, a client application can more efficiently use network, CPU and memory resources. By contrast, an application that retrieves a full API feed, parses it and then drops unused fields is likely to waste some resources along the way. Over time, as resources add more fields, the benefits of using partial responses will only increase since the client application will not be requesting newly introduced properties that it doesn't support.

Requesting a Partial Response

You can a partial response from any API endpoint that has a fields URL parameter. The fields URL parameter must be URL encoded.

Understanding the Fields Parameter

The fields parameter filters the API response so that the response only includes a specific set of fields. The fields parameter lets you remove nested properties from an API response and thereby reduce your bandwidth usage. The following rules explain the supported syntax for the fields parameter value, which is loosely based on XPath syntax:

• Use a comma-separated list ( fields=a,b ) to select multiple fields.
• Use an asterisk ( fields=* ) as a wildcard to identify all fields.
• Use parentheses ( fields=a(b,c) ) to specify a group of nested properties that will be included in the API response.
• Use a forward slash ( fields=a/b ) to identify a nested property.

In practice, these rules often allow several different fields parameter values to retrieve the same API response. For example, if you want to retrieve the playlist item ID, title, and position for every item in a playlist, you could use any of the following values:

• fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position

• fields=items(id,snippet/title,snippet/position)

If you desire to filter more than two levels deep, we suggest that you use the parent/child method of identifying the child element as in the above example.