Developer Portal for YouTrack and Hub 2021.3 Help

Hub API Field 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://hub.project.com/api/rest/users/6b965961-846b-43b4-92be-2e40664ca81b

Full resource response: The full resource data includes the following fields, along with many others that we have omitted for brevity.

{ "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "name": "Robin Taylor", "projectRoles": [ { "type": "projectRole", "id": "0173bba0-c99e-4189-b9a3-0bee2dbf2eb1", "role": { "id": "fbcd7c28-16d4-4531-925b-81fc7f35b1b9", "key": "system-admin", "name": "System Admin" }, "project": { "id": "0" }, "owner": { "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "login": "admin" } } ], "transitiveProjectRoles": [ { "type": "projectRole", "id": "47db71a0-aae1-47b3-97ca-e3e3a0e544e3", "role": { "id": "9c1cee56-e697-4c23-8f0f-73ac250ac1fc", "key": "observer", "name": "Observer" }, "project": { "id": "0" }, "owner": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } } ], "sourcedProjectRoles": [ { "type": "sourcedProjectRole", "id": "47db71a0-aae1-47b3-97ca-e3e3a0e544e3", "role": { "id": "9c1cee56-e697-4c23-8f0f-73ac250ac1fc", "key": "observer", "name": "Observer" }, "project": { "id": "0" }, "owner": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" }, "sources": [ { "type": "groupProjectRoleSource", "group": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } } ] }, { "type": "sourcedProjectRole", "id": "0173bba0-c99e-4189-b9a3-0bee2dbf2eb1", "role": { "id": "fbcd7c28-16d4-4531-925b-81fc7f35b1b9", "key": "system-admin", "name": "System Admin" }, "project": { "id": "0" }, "owner": { "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "login": "admin" }, "sources": [ { "type": "ownRoleSource" } ] } ], "transitiveOrganizationRoles": [ { "type": "organizationRole", "id": "968c5d04-7afa-4397-b001-231a310abece", "role": { "id": "ed3b37a3-1f4c-4385-8e6d-5e2d37a8e91a", "key": "developer", "name": "Developer" }, "organization": { "id": "d706e386-da81-409d-b719-9245c1db681c" }, "owner": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" } } ], "sourcedOrganizationRoles": [ { "type": "sourcedOrganizationRole", "id": "968c5d04-7afa-4397-b001-231a310abece", "role": { "id": "ed3b37a3-1f4c-4385-8e6d-5e2d37a8e91a", "key": "developer", "name": "Developer" }, "organization": { "id": "d706e386-da81-409d-b719-9245c1db681c" }, "owner": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" }, "sources": [ { "type": "groupRoleSource", "group": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" } } ] } ], "login": "admin", "banned": false, "guest": false, "avatar": { "type": "urlavatar", "url": "http://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "profile": { "avatar": { "type": "urlavatar", "url": "http://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "email": { "type": "EmailJSON", "verified": false, "email": "robin.taylor@project.com" }, "locale": { "name": "en", "language": "en" } }, "groups": [ { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } ], "transitiveGroups": [ { "type": "userGroup", "id": "b5bfba7c-98cb-4b58-a52a-5fff0077a7a7" } ], "teams": [ { "type": "projectTeam", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef" } ], "transitiveTeams": [ { "type": "projectTeam", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef" } ], "details": [ { "type": "LoginuserdetailsJSON", "id": "a1aca5f7-ceb2-471a-906e-7a05c1ef35e6" } ], "VCSUserNames": [ { "name": "robin.taylor@project.com" } ], "creationTime": 1500362592707, "lastAccessTime": 1615297793582, "permanentTokens": [ { "id": "61-2" } ], "favoriteProjects": [ { "id": "d52e93b2-25fa-41c9-b0e1-c59b0edaac2e" } ], "endUserAgreementConsent": { "accepted": true, "majorVersion": 1, "minorVersion": 0, "time": 1519287697590, "address": "10.0.75.1" }, "requiredTwoFactorAuthentication": false, "pendingTwoFactorAuthentication": { "type": "TwoFactorAuthenticationSecretJSON" } }

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://hub.project.com/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355?fields=name,banned,avatar/url,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.

{ "type": "user", "name": "Robin Taylor", "banned": false, "avatar": { "type": "urlavatar", "url": "https://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "groups": [ { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc", "name": "Registered Users" }, { "type": "userGroup", "id": "fb70e9df-d97b-4350-a289-372e39ebba2a", "name": "Developers" }, { "type": "userGroup", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef_team", "name": "Team Tools Team" }, { "type": "userGroup", "id": "edf6bc5f-6b79-483b-8c35-5b8a78876e02_team", "name": "Academy Team" }, { "type": "userGroup", "id": "8a985f08-16af-4e5d-85d2-9cc26dbb14c1_team", "name": "edX Team" }, { "type": "userGroup", "id": "cc6e23ba-b963-4aeb-8869-a2eebc0a9d05_team", "name": "Customer Feedback Team" } ] }

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.

  1. Use a comma-separated list to select multiple fields.

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

  3. Use a sub-selector to request a set of specific sub-fields of arrays or objects by placing expressions in parentheses "( )".

  4. Use wildcards in field selections, if needed.

Last modified: 13 July 2021