Select fields (fields)

This section provides information about selecting fields to be returned by the REST API.

Overview

You can specify the fields to be returned from the server in the response to a GET operation on a collection.

Using the fields clause is useful when getting certain fields that are not listed by default, often for performance reasons. Some examples of fields not returned by default are: user-defined fields, comments, attachments, runs, and run steps.

The fields parameter

Select fields with the fields parameter. The fields parameter has the following syntax:

fields=<field name>[[,<field name>]]

The field's ID and type are always returned regardless of the fields you select.
Field names are separated by commas: ,
When requesting an entity without explicitly specifying field names, the following fields are returned: id, workspace_id, type, subtype, and logical_name.

Examples

The following are examples of using the GET operation to return fields.

Get all defects, making sure to display the name field.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id,name

{
    "total_count": 3,
    "data": [
        {
            "type": "defect",
            "name": "Emptying out items in cart takes way too long",
            "id": "1014"
        },
        {
            "type": "defect",
            "name": "Shortcut key for deleting all items in cart does not work.",
            "id": "1012"
        },
        {
            "type": "defect",
            "name": "When adding one item to cart, it appears as if the item was added two times.",
            "id": "1013"
        }
    ],
    "exceeds_total_count": false
}

Get comments for an entity

For performance optimization, when getting entities, comments are not included in the response. To see comments, you have to explicitly request them using the fields clause.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=comments

Reference fields (technical preview)

You can also get an entity's reference fields. For example, you can get the name and status of tests associated with a requirement.

This API is recursive up to three levels, meaning you can request reference fields for reference fields. For example, you can request requirements, their associated tests, the application modules of the tests, and fields for those application modules.

Note:

The API returns only selectable fields that are public or technical preview.
The API is not designed to fetch all stored data in one request. In most cases, it should be used to fetch data of the directly referenced entity.
The ability to expand reference fields is supported only when reading a collection of entities.
Additional default fields of the reference field are returned together with the requested fields.

Examples:

Add release information (default fields only):
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id,name,release
Add release information (expand release fields beyond defaults):
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id,name,release{id,name,start_date,end_date}
Add team information (expand team fields two levels beyond defaults):
GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id,name,team{id,name, team_lead{id,full_name,email}}