Working with Helix ALM REST API Part 2: Filtering

Today we'll be continuing our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about using filters to limit the number of items returned by a request. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization's Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization's workflow, with few limitations.

The REST API is available at:
https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:
https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:
../Perforce/Helix ALM/helix-alm-rest-api/config/config.json
on the machine that is running the Helix ALM instance.

REST API Features

Filtering

When throughput or bandwidth is an issue, or a subset of items is needed, the Helix ALM REST API allows calls to pass a set of query parameters to return a limited amount of items.

Fields

The fields parameter returns only the specified fields back with the items. The parameter is an array of strings and comma separated. The fields parameter is included after the URL of the endpoint.
An example looks like:
…/issues?fields=Status,Summary,Description
Here we are returning only the fields "Status", "Summary", and "Description" with each Issue item. If a field has a space then it must be wrapped in single quotes, e.g. 'Has Attachments'.
Lists of fields can be gotten from the Fields endpoints,
/{projectID}/configs/fields/{fieldItemType}/customFields
and
/{projectID}/configs/fields/{fieldItemType}/systemFields
where {fieldItemType} is one of the following:

• document fields
• issue fields
• requirement fields
• test case fields
• test run fields
• test variant fields

Search

The search parameter queries the API for items that match the specified criteria. The parameter is a string of fields with search operators and the search value. The search parameter is included after the URL of the endpoint.
Let's look at an example.
…/testCases?search=Summary CONTAINS 'text in summary'
This example searches for test case items where the summary field contains the specified text. To chain multiple search terms together a logical operator of "and", "or", or "not" needs to be used.
For example:
…?search=Summary CONTAINS 'text in summary' AND Status = 'Open'

This example will look for items that contain the specified text in the summary field and also have the "Open" status. More detail about the search operators below. The logical operator is case-insensitive. 
It's important to note that a search query must be properly encoded for the URL, with the following characters escaped with their percent sign values:

/ ? : @ - . _ ~ ! $ & ' ( ) * + , ; =

Taking our previous example, the query now becomes:

…?search=Summary%20CONTAINS%20%27text%20in%20summary%27%20and%20Status%20%3D%20%27Open%27

Be careful escaping the initial '=' after search as this is needed to indicate the start of the search query, and any subsequent '&' symbols for combining URL parameters, such as 'search=…&fields=…'

Paging

Paging can be used to reduce the amount of items returned per request. By default, the API returns 300 items per page unless the "per_page" parameter is set. The page parameter is used for navigating between the pages and fetching the next batch of items.
In the response object, there is an additional section with paging information.
The paging object looks like:

"paging": {
  "page": {page number},
  "pageLimit": {item limit per page},
  "totalCount": {total items},
  "totalPages": {total pages},
  "links": [
    {
      "ref": "self",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "first",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "last",
      "href": "{url}",
      "method": "GET"
    },
    {
      "ref": "next",
      "href": "{url}",
      "method": "GET"
    }
  ]
}

Page number is the current page number of the response. Page limit is the number of items per page. Total count is how many items there are in total. Total pages is how many pages there are in total.
The page and per_page parameters are included in the query. An example of the query in the URL looks like:
…?page=1&per_page=10

Operator syntax

There are three logical operators and ten comparison operators for constructing a query.
The logical operators are: "and", "not", and "or".
The comparison operators are:

EQUALS or =
This operator looks for an exact match of the value from the specified field

NOT EQUALS or !=
A combination of the logical "not" and the equals comparison operator.

GREATER or >
Applies to numeric and date-date/time fields

GREATER_EQUAL or >=
Applies to the same fields as GREATER

LESS or <
Applies to the same fields as GREATER

LESS_EQUAL or <=
Applies to the same fields as GREATER

IN or :
Applies to lists, folder, and number fields.
Syntax is: Field IN ('value-1', 'value-2'), equivalent to Field = 'value-1', or Field = value-2.

IN_RECURSE or :?
Performs a recursive comparison in folders.

CONTAINS or ~
Applies to text only fields for a case-insensitive comparison of the supplied string value with the specified field.

CONTAINS_CASE or ^
Applies to text only fields for a case-sensitive comparison of the supplied string value with the specified field.

In addition to these operators, Boolean values are "true" and "false".

For menu fields that have not been assigned a value, the value "NOT_SET" can be used, e.g. Product = NOT_SET.

Conclusion

The Helix ALM REST API provides developers with powerful and flexible ways to interact with their Helix ALM instance through various filtering mechanisms. By utilizing fields, search parameters, and paging options, developers can efficiently retrieve and manage data while optimizing performance. The API's comprehensive set of operators - including logical, comparison, and specialized operators for different data types - enables precise querying capabilities. This flexibility, combined with proper URL encoding and pagination handling, makes the API a robust tool for integrating Helix ALM into an organization's development workflow. 

Whether developers need to retrieve specific fields, search for particular items, or manage large datasets through paging, the API provides the necessary functionality to create effective tools and automation scripts.

---

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain filtering with the API. In part 3 we will look at the API's conventions and exceptions.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.