Select fields (fields)

This section provides information about selecting fields to be returned by the ALM Octane 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.

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

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
}

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 (e.g. 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.

    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 currently only supported when reading a collection of entities.

    Example:

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