ALM REST API Reference (Core) Overview


Using the REST API, you can create a client application to create, read, update, and delete entities on the ALM (Application Lifecycle Management) platform. Without any coding, you can also use a browser as your client to read information from ALM.

The ALM REST API is for use by web programmers familiar with RESTful API technology.

Before working with this API, read the General Notes and Limitations

The first step of a client application is authenticating the user. Authentication is handled by an external Identity Provider (IdP), and must follow the WS_Trust authentication protocol. After a client is authenticated, it can work with ALM entities.

An ALM entity is a complete functional unit of information. Entities are members of collections. Collections are represented by data in XML format that conforms to the Entities Collection Schema or by equivalent strings in JSON format. The properties of an single entity are represented by data in XML format that conforms to the Entity Schema or by the equivalent JSON string.

Examples of entity types are defect, requirement, test, run, and folder. An individual entity is identified by the collection it belongs to and its ID. For example, /tests/23 or /tests/23/attachments/IntroductionToREST.doc.

Some resources support or require other formats. The resource-specific details are in each resource's reference page.

To specify the format for the return value, use an Accept header. To specify the format for submitted data, use a Content-Type header. The header value is usually one of application/json or application/xml. For ad-hoc queries, especially from a browser, an alt clause can be used instead of an Accept header.

When getting a collection, the results can be filtered, ordered, and grouped by different fields. Fields are identified by logical names.

The data is returned in pages. The client application must request each page. The first page is returned by the first GET. Using XML or JSON, all subsequent GET operations specify the first entity to return. See Data Paging.

An entity is created with a POST on a collection. An existing entity is changed with a PUT operation on the specific entity. The entity data is passed in XML or JSON format.

An entity is deleted with a DELETE on the specific entity.

In addition to entity and entity collection resources, there are:

  • customization resources that provide data on entity fields, site users, permissions, subtypes, and project lists
  • entity support resources such as attachments and file storage
  • general resources that apply to the whole site or to all entities
  • version control operations
  • user settings, called favorites

See Also

Network Working Group RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
Network Working Group RFC 2616 Section 10: Status Code Definitions