Fields request syntax is based on Google Partial request syntax. The following text is an applicable to the Hub API quote from the Google API documentation.
By default, the server sends back all immediate fields of a resource after processing requests. For nested objects, only the basic info (for example,
id) is returned by default. To enhance the performance, you can request the server to return 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.
The following example shows the use of the
fields parameter with a sample API.
Simple request: This HTTP GET request omits the
fields parameter and returns the full resource.
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
Request for a partial response:
The following request for this same resource uses the fields parameter to significantly reduce the amount of data returned and the number of requests required to get details about nested objects.
In response to the request above, the server sends back a response that contains only the basic user information with a list of named user groups.
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.
Summary of Fields Parameter Syntax
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.
a/bto select a field
bthat is nested under the field
a/b/cto select a field
cnested under the
Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses
Use wildcards in field selections, if needed.