Partial Requests

When you make a request to Hub REST API, potentially you may pull the full graph of all Hub objects. Normally, you just don't need such an amount of data.

By default, the Hub API returns only simple fields (for example, strings, integers, 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.

Let's see how partial requests work in Hub API on an example.

Let's request parameters of a user account:

GET https://hub.example.com/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": "https://hub.example.com/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": "https://hub.example.com/rest/roles/2d2ae9db-365f-486e-bac8-021af86f1444",
                    "name": "System Admin"
                },
                "project": {
                    "id": "0",
                    "url": "https://hub.example.com/rest/projects/0"
                }
            }],
            "contacts": [{
                "type": "emailJSON",
                "verified": false,
                "email": "admin@jetbrains.com"
            }],
            "groups": [{
                "id": "f4495122-993f-4005-b6be-7823f3bcac2d",
                "url": "https://hub.example.com/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://hub.example.com/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: 17 February 2020