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 (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.

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.

GET https://sso.jetbrains.com/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355

Full 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": "John Smith",
    "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": "john.smith@example.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.

GET 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": "John Smith",
    "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 under the field a; use a/b/c to select a field c nested under the 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.

Last modified: 17 December 2018