Fields Syntax
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 (e.g. id) is sent by default. 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.
Example
The following example shows the use of the fields parameter with a sample API.
Simple Request
Simple request: This HTTP GET request omits the fields parameter and returns the full resource.
https://sso.jetbrains.com/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355Full resource response: The full resource data includes the following fields, along with many others that have been omitted for brevity.
{
"id": "6109acd8-598b-44db-9e85-e99f3adca355",
"url": "http://hub-dev.labs.intellij.net:8080/accounts/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355",
"name": "Maxim Mazin",
"banned": false,
"avatar": {
"url": "http://hub-dev.labs.intellij.net:8080/accounts/api/rest/avatar/6109acd8-598b-44db-9e85-e99f3adca355",
"pictureUrl": "http://www.gravatar.com/avatar/3cc02cb9c88aada5761bdf22786e76f6.jpg?d=retro"
},
"contacts": [
{
"type": "EmailJSON",
"verified": true,
"email": "maxim.mazin@gmail.com"
},
...
],
"groups": [
{
"id": "309ffb10-1cd4-4e90-9b86-1dbaded92319",
"url": "http://hub-dev.labs.intellij.net:8080/accounts/api/rest/usergroups/309ffb10-1cd4-4e90-9b86-1dbaded92319"
},
...
],
"details": [
{
"type": "EmailuserdetailsJSON",
"id": "c6903529-7f85-4d9c-b9c5-52fe38f07a37"
},
...
],
"aliasIds": [
"43e730f8-56cd-4957-8e15-c6ce17c49276",
...
]
}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.
https://sso.jetbrains.com/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355?fields=name,banned,avatar/pictureUrl,groups(id,name)Partial response
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.
{
"name": "Maxim Mazin",
"banned": false,
"avatar": {
"url": "http://hub-dev.labs.intellij.net:8080/accounts/api/rest/avatar/6109acd8-598b-44db-9e85-e99f3adca355",
"pictureUrl": "http://www.gravatar.com/avatar/3cc02cb9c88aada5761bdf22786e76f6.jpg?d=retro"
},
"groups": [
{
"id": "309ffb10-1cd4-4e90-9b86-1dbaded92319",
"name": "New Users"
},
{
"id": "51ab66f5-bbfe-4345-9447-93ea8b5db3ee",
"name": "Admins"
},
...
]
}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.
- Use a/b to select a field b that is nested within field a; use a/b/c to select a field c nested within b.
- 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.