Using REST API

This topic contains the following high-level information about the REST API provided in BMC Release Process Management:

Introduction to REST API in BMC Release Process Management

BMC Release Process Management uses a representational state transfer (REST) API for invoking functionality. In the context of the product, a REST-ful approach entails the following design commitments:

Collection and member endpoints based on plural model names (For example, "v1/requests" and "v1/requests/[id]")
HTTP verbs map to allowed activities:
1. GET /collection returns the index or list view of a collection
2. GET /collection/[id] returns an individual member of a collection
3. POST /collection adds a member to a collection based on submitted data
4. PUT /collection/[id] updates an individual member based on submitted data
5. DELETE /collection/[id] attempts to delete an individual member of a collection. If the delete functionality is not available for the specified collection, the appropriate member of the collection becomes inactive or archived.
HTTP status codes are returned to indicate status of request (For example, 200 OK or 404 Not Found) — see Error-codes-for-REST-API for latest list
JSON and XML formats are supported for retrieval and posting, in addition to URL parameters

Tip

The value shown in the examples that follow as "[id]" is the primary key field for that record assigned by the database. In most cases, this will match the id shown in the URL of the user interface. Requests are an important exception because they display in the URL and on screen a more readable "request_number" which is typically a constant such as 1,000 plus the primary key id. A request with a primary key of 24 would have a visible request number of 1024. For REST calls to a request to work properly, the database ID must be calculated: "v1/requests/24" would be the proper end point for the request example above.

REST API endpoints

The REST API is handled by a parallel set of controllers that run alongside the user interface controllers. The URL for REST calls is the same as the user-interface URL, including any ports or JBoss namespace. For example, if users want to access BMC Release Process Management at https://www.example.com:8443/brpm/, they must place the endpoint after the brpm in this URL. In a typical JBoss installation, the port and the namespace for the web application brpm are required. The full address for an API call to get a list of components would be https://www.example.com:8443/brpm/v1/components.

Generating a REST API token

To get the REST API token, do the following:

Log in to BMC Release Process Management.
At the top-right corner of the screen, click Profile, and then click Show next to the API Key.
Copy the API Key Value and insert it instead of [api_token] in the REST call example.

Tip

In the REST call examples that follow, this token is shown as [api_token] and must be replaced with a valid value for your system.

Regenerating a REST API token

By default, REST API token is generated for a user when the user is created. Starting with version 5.0.03.003, you can regenerate the token using a rake task.

To regenerate a REST API token

Go to RPMhome\releases\yourCurrentVersion\RPM\portal.war\WEB-INF and set the environment variable by running the following command.
./opt/bmc/RLM/bin/setenv.sh
Run the following rake task.
jruby -S rake user:regenerate_api_key[userName1,userName2, ..] RAILS_ENV=production
Replace userName with the user name for whom you want to regenerate the API token. Separate multiple user names with commas.
Press Enter.
After the rake task is executed successfully, the following sample message is displayed.
New api key regenerated for user 'mrane'

From Service Pack 7 of BMC Release Process Management 5.0, users must pass the API token within single quotes in curl commands.

Example

curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/apps?token='$2a$10$aXSI7ymCJKXWvaH.rqeAhO3gND5U2kFlGHnR7vUAVsXnaCZAn1hpC'

REST clients

A REST API can be consumed by a variety of HTTP clients, such as cURL, Wget, and REST client interfaces in common programming languages.

Note

The functions present on the REST API version 1 and REST API version 2 pages are shown using cURL HTTP client.

Supported models

For the complete list of functions that can be performed in BMC Release Process Management navigate to the following for each version: