Partial Requests

When you make a request to Hub RESTful API, potentially you may pull the full graph of all Hub objects. Normally, this is not what is required. By default, Hub API returns only simple fields (for example, strings, numbers, booleans) of the requested object plus object fields represented by their IDs, URLs, etc.

For example:

GET http://munit-044:8080/accounts/rest/users/794faf72-ba29-447e-8984-3442207cbebb
    {
        "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 sub-tree that you want to get in the response, use Google API-like partial requests.

GET http://munit-044:8080/accounts/rest/users/794faf72-ba29-447e-8984-3442207cbebb?fields=name,groups/name,contacts(verified,email,jabber)
    {
        "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: 19 July 2017