Resources

Resources are identified by URIs.

Overview

Resources are identified by URIs, and can be either:

An instance, such as a defect.
A collection, such as defects.

A strict set of request methods are allowed for a resource type. Resources support the JSON representation type.

Tip: For a comprehensive list of supported public resources and their details, see the description of the Interactive API client.

Public resources

You do not need to send any additional headers, other than the content-type header, when sending REST API requests for public resources.

For details on generic and CI/CD resources, see the Interactive API client.

The following public, supported resources are available.

Metadata resources
CI/CD resources
Generic resources
Custom resources

Metadata resources

CI/CD resources

builds
ci_servers
pipelines

Generic resources

application modules
epics
features
stories
defects
phases
metaphases (GET only)
transitions
tasks
releases
requirements
requirement_documents
requirement_folders
requirement_roots
sprints
product_areas
teams

team_sprints
tests
manual tests
gherkin_tests
test_suites
test_suite_link_to_automated_tests
test_suite_link_to_gherkin_tests
test_suite_link_to_manual_tests
manual_runs
suite_run
run_steps
runs
automated_runs
previous_runs
pipeline_run
pipeline_node
ci_build

scm_commit
list_nodes
users
user_items
work_items
work_item_roots
roles
workspaces
workspace_roles
workspace_users
user_tags (GET and POST)
taxonomy_category_nodes
taxonomy_item_nodes
taxonomy_nodes
timeline
attachments
comments

Note: The product_area resource is also known as an application_module.

Custom resources

Technical preview resources

Resources not listed above as public are subject to change until declared public. To access these resources, send REST API requests with a header:

Header: ALM-OCTANE-TECH-PREVIEW

Value: true

Two examples of technical preview resources, are coverage and logs. For details, see Add coverage (technical preview) and Add a log (technical preview).

Resource hierarchy

Resources are built as a hierarchy of collections and instances.

Some resources are singleton resources, such as: test-results, sign_in, and sign_out.

The following example represents a resource collection of humans. This collection contains resource instances of human. Since humans have limbs, every human contains a collection of limbs. This collection contains resource instances of limb. Since limbs have fingers, every limb contains a collection of fingers. This collection contains resource instances of finger.

Example:

humans
    human
          limbs
               limb
                    fingers
                         finger
                         finger
               limb
                    fingers
                         finger
                         finger
     human
          limbs
...

Resource naming conventions

Use the following resource naming conventions.

Resource	Description
Name	Since resources represent entities, resource names should represent the entities' names. Example: defect
Instance	Resource instances should be called by their names in singular. Example: defect
Collection	Resource collections should be called by their names in plural. Example: defects
Split name	A resource whose name is more than one word should be separated by the underscore symbol. Example: ci_servers