Partial Requests

When you make a request to Hub RESTful API, potentially you may pull the full graph of all Hub objects. Normally, such amount of data is simply not required.

By default, the Hub API returns only simple fields (for example, strings, numbers, booleans) of the requested object and object fields represented by their IDs, URLs, and so on. To customize the subset of object fields that you want to get in the response, use Google API-like partial requests.

Lets see how partial requests work in Hub API on an example.

Let's request parameters of a user account:

GET http://munit-044:8080/accounts/rest/users/794faf72-ba29-447e-8984-3442207cbebb

As the request does not contain a parameter to customize the response, Hub returns all the parameters in the response body:

{
    "id": "794faf72-ba29-447e-8984-3442207cbebb",
    "url": "http://munit-044.labs.intellij.net:8080/accounts/rest/users/794faf72-ba29-447e-8984-3442207cbebb",
    "name": "admin",
    "banned": false,
    "avatar": {
        "pictureUrl": "http://www.gravatar.com/avatar/cc90309659114c3979c9b469f44252e7.jpg&?d=monsterid&s=60"
    },
    "roles": [{
        "id": "12f8c35a-ef03-4304-869d-690315c690e8",
        "role": {
            "id": "2d2ae9db-365f-486e-bac8-021af86f1444",
            "url": "http://munit-044.labs.intellij.net:8080/accounts/rest/roles/2d2ae9db-365f-486e-bac8-021af86f1444",
            "name": "System Admin"
        },
        "project": {
            "id": "0",
            "url": "http://munit-044.labs.intellij.net:8080/accounts/rest/projects/0"
        }
    }],
    "contacts": [{
        "type": "emailJSON",
        "verified": false,
        "email": "admin@jetbrains.com"
    }],
    "groups": [{
        "id": "f4495122-993f-4005-b6be-7823f3bcac2d",
        "url": "http://munit-044.labs.intellij.net:8080/accounts/rest/usergroups/f4495122-993f-4005-b6be-7823f3bcac2d"
    }],
    "details": [{
        "type": "emailuserdetailsJSON",
        "id": "06cfc5b5-4cce-4aa7-8652-fb9ac1c920ff"
    }]
}

To customize the returned sub-set, we add the fields parameter to the request:

GET http://munit-044:8080/accounts/rest/users/794faf72-ba29-447e-8984-3442207cbebb?fields=name,groups/name,contacts(verified,email,jabber)

In this case, the response body contains only specified fields of the user account:

{
    "name": "admin",
    "contacts": [{
        "type": "emailJSON",
        "verified": false,
        "email": "admin@jetbrains.com"
    }],
    "groups": [{
        "name": "New Users"
    }]
}

Hub client library allows building of partial requests programmatically in the type-safe manner.

UserJSON user = accountsClient.getUserClient().getUser(userId,
Partial.user(
    Partial.User.NAME,
    Partial.User.GROUPS(
        Partial.UserGroup.ID,
        Partial.UserGroup.NAME
    ),
    Partial.User.CONTACTS(
        Partial.Contact.VERIFIED,
        Partial.Email.EMAIL
    )
)
);

Last modified: 22 May 2018