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
- GET /collection returns the index or list view of a collection
- GET /collection/[id] returns an individual member of a collection
- POST /collection adds a member to a collection based on submitted data
- PUT /collection/[id] updates an individual member based on submitted data
- 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 your users access BMC Release Process Management at http://www.example.com:8080/brpm/, place all of the endpoints shown in the following table after the brpm in that 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 http://www.example.com:8080/brpm/v1/components.

REST API token

To get the REST API token, you must be an administrator user. Go to your profile screen and click Show next to the API key.

Tip

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

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. The examples that follow use curl.

Supported models

The following functions can be performed in BMC Release Process Management by using REST API:

Model name	Endpoints	Description
activity_logs	/v1/activity_logs /v1/activity_logs/[id]	Activity logs are audit entries written when significant events in the core process models, like requests and steps, occur.
apps	/v1/apps /v1/apps/[id]	Applications are software units that can be assigned to environments and deployed through requests.
business_processes	/v1/business_processes /v1/business_processes/[id]	Business processes are used for categorizing requests to enable planning and reporting.
categories	/v1/categories /v1/categories/[id]	Categories are metadata elements that group requests for reporting.
components	/v1/components /v1/components/[id]	Components are abstract software sub-units. They might be used as installed components when they are assigned to a particular application and environment.
constraints	/v1/constraints /v1/constraints/[id]
deployment_windows	v1/deployment_windows/series v1/deployment_windows/series/[id]	Deployment windows are special calendar events for allowing or preventing the access the specific environments.
environments	/v1/environments /v1/environments/[id]	Environments are designated collections of servers and other resources, for example, Quality Assurance, User Acceptance Testing, Production, and Cloud environments.
environment types	/v1/environment_types /v1/environment_types/[id]	Environment types are used to categorize the environments.
groups	/v1/groups /v1/groups/[id]	Groups are ad hoc organizational units of users collected for reporting or mass assignment to teams.
installed_components	/v1/installed_components /v1/installed_components/[id]	Installed components are components that are assigned to a particular application and environment pair.
job_runs	/v1/job_runs /v1/job_runs/[id]	Job runs are created by internal background workers and can be used to track automation progress in a read-only manner.
list_items	/v1/list_items /v1/list_items/[id]	List_items permit string and integer values to be stored in lists that determine BMC Release Process Management program behavior or new user-defined dictionaries (see also lists).
lists	/v1/lists /v1/lists/[id]	Lists permit interface elements to be configured as well as user-defined lists to be created (see also list_items).
notification_templates	/v1/notification_templates /v1/notification_templates/[id]	Notification templates provide liquid template-based email configuration for system notification events.
package_contents	/v1/package_contents /v1/package_contents/[id]	Package contents are metadata elements that group steps for reporting.
phases	/v1/phases /v1/phases/[id]	Phases are metadata elements that group steps for reporting.
plan_stages	/v1/plan_stages /v1/plan_stages/[id]	Plan stages are the major scheduling gates of a release plan template, such as Quality Assurance, Staging, or Production.
plan stage instances	/v1/plan_stage_instances /v1/plan_stage_instances/[id]
plan routes	/v1/plan_routes /v1/plan_routes/[id]
routes	/v1/routes /v1/routes/[id]
route gates	/v1/route_gates /v1/route_gates/[id]
plan_templates	/v1/plan_templates /v1/plan_templates/[id]	Plan templates are saved collections of stages and request templates that structure and populate new release plans with requests.
plans	/v1/plans /v1/plans/[id]	Plans are instances of a particular plan template to which runs and requests can be assigned.
procedures	/v1/procedures /v1/procedures/[id]	Procedures are collections of steps that you can reuse in multiple requests and associate with applications.
properties	/v1/properties /v1/properties/[id]	Properties are name-value pair storage with an audit log of all past values and polymorphic associations with a variety of models.
project_servers	/v1/project_servers /v1/project_servers/[id]	Project servers contain integration servers for Rally, ServiceNow, and other supported integrations.
releases	/v1/releases /v1/releases/[id]	Releases are tags for requests and plans to be used for reporting.
request_templates	/v1/request_templates /v1/request_templates/[id]	Request templates are a convenient way to save effective requests and steps for reuse.
requests	/v1/requests /v1/requests/[id]	Requests are the primary process model for a release, belonging to plans and containing steps and procedures.
runs	/v1/runs /v1/runs/[id]	Runs are process models, belonging to plans and organizing a set of requests for serial or parallel execution.
server_groups	/v1/server_groups /v1/server_groups/[id]	Server groups are collections of servers.
servers	/v1/servers /v1/servers/[id]	Servers are logical computer names that can be assigned to installed components and have properties.
steps	/v1/steps /v1/steps/[id]	Steps are process models that belong to requests, can be grouped in procedures, and do manual or automated work.
teams	/v1/teams /v1/teams/[id]	Teams are collections of users for which access permissions may be set for many users at once.
tickets	/v1/tickets /v1/tickets/[id]	Tickets are internal markers for outside ticketing services (JIRA, Rally, and so on) that can be assigned to plans, requests, and steps.
users	/v1/users /v1/users/[id]	Users are system or external (LDAP) resources controlling program access and roles.
version_tags	/v1/version_tags /v1/version_tags/[id]	Version tags are an authority table of versions for installed components that scope the available versions for request steps.
work_tasks	/v1/work_tasks /v1/work_tasks/[id]	Work tasks are metadata models by which steps can be categorized for reporting.