Select fields (fields)

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

In this topic:

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.

Back to top

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: ,

• Requesting an entity without explicitly specifying the desired field names, will return only the following fields: id, workspace_id, type, subtype, and logical_name.

Back to top

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

Back to top

Reference fields (technical preview)

You can also get reference fields for an entity.

For example, suppose you want to get requirements and their associated tests. Using the public API described above, the response would include the ID of the entity (requirement), the ID of the referenced entity (associated test), and its type (for example, manual test).

In the technical preview API, you can specify fields that will be returned for the referenced entity by expanding upon default fields that are usually retrieved (such as ID and type). For example, you can get the name and status of the tests associated with the requirements.

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.

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}}

Back to top

See also:

• Querying a collection
• Sort results (order_by)
• Query