Working with Helix ALM REST API Part 3: Conventions & Exceptions

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 the API's conventions and exceptions. 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.

API Conventions and Exceptions

Case Sensitivity

The API is case sensitive except for field names in the following areas, which are not case sensitive:

• Search parameters
• PUT and POST fields array
• 'fields' parameter that indicates the fields to return (URL parameter and POST search)

What this means in terms of constructing the request is that the URL's search and field query parameter can look like:

/{endpoint}?search=PRODUCT = 'Wysi CRM'
/{endpoint}?fields=sUmMaRy,DESCRIPTION,product

Note: the specified criteria of the search parameter is still subject to case sensitivity.

The fields array in a PUT or POST body is the same as the above example in terms of case insensitivity and applies to the label value in the field object.

"fields": [
  {
    "label": "SUMMARY",
    "string": "New issue from REST API"
  },
  {
    "label": "prOduCt",
    "menuItem": {
      "label": "Activity Professional Suite (APS)"
    }
  }
]

Note: the label of the menu item object is case sensitive.

Date Formatting

Date and date/time values are always specified in ISO 8601 extended format for UTC (GMT) time. For example:

• 2025–01–01
• 2025–01–01T00:00:00Z

The Helix ALM REST API returns dates and date/time information in the above format when requested. Serializing dates and date/time depends on the programming language used. In C#, serializing DateTime objects to ISO 8601 is done by default. An example of one such language that does not support the format by default is Python. To achieve this in Python, it requires the use of the datetime's "isoformat()" method.

import json
from datetime import datetime

current_time = datetime.now()
iso8601_string = current_time.isoformat()
json_string = json.dumps({'timestamp': iso8601_string})

Be sure to check the documentation of your chosen programming language to ensure that Datetime objects match Helix's format.

Numbers

Numeric values must be represented in a consistent format regardless of the locale or region where the Helix ALM REST API is being used. Different locales may have different conventions for representing numbers, such as using commas or periods as decimal separators. However, the API expects decimal numbers to always use a period (.) as the decimal separator, regardless of the locale.
Valid:

{
  "decimal": 3.1,
  "id": 1,
  "label": "Decimal Field",
  "type": "decimal"
}

Invalid:

{
  "decimal": 3,1,
  "id": 1,
  "label": "Decimal Field",
  "type": "decimal"
}

Special Characters and Spaces in Field Names

Field names and values that contain spaces or special characters may cause searches to fail and return 400. In order for searches to work properly with these fields, the names and values must include quotes around them.
In terms of the search query parameters in a URL, this looks like:

/{endpoint}?search='Versions Impacted' = '1.0'

Note: for readability, the spaces and special characters are not URL-escaped.

In a POST search, the query would look like:

{
  "search": "'Versions Impacted' = '1.0'",
  "fields": [
    "summary",
    "description",
    "status"
  ],
  "page": 1,
  "per_page": 20,
  "formattedText": true
}

Field names that contain commas are not supported in URL search query parameters. Instead, use the POST search endpoint because JSON supports commas.

Conclusion

Understanding these API conventions and exceptions is crucial for successful integration with the Helix ALM REST API. By following the guidelines for case sensitivity, date formatting, number representation, and handling of special characters, you can avoid common pitfalls and ensure their API requests are properly formatted. Remember to pay special attention to field naming conventions, use appropriate date formats based on your programming language, maintain consistent number formatting regardless of locale, and properly quote fields containing spaces or special characters. When working with complex field names, particularly those containing commas, utilize the POST search endpoint instead of URL parameters. These standards help maintain consistency and reliability across all API interactions.

---

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain some of the idiosyncrasies of the API. In part 4 we will look at the API's errors and response codes.

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.