Consuming BMC Atrium Core in external applications using REST API
This section and topics under this section applies to BMC Atrium Core 9.1.03 and later.
You can interact with and control BMC Atrium Core from a remote computer by using a script or program that uses REST API. From BMC Atrium Core 9.1.03, the REST API support the following additional tasks:
- Querying CMDB classes and attributes
- Creating one or more CMDB instances
- Updating or deleting one or more CMDB instances
The REST API enable you to perform most tasks that you can currently perform through BMC Atrium CMDB or command-line utilities. For more information, see Endpoints in the REST API .Additionally, the Remote Procedure Call (RPC) API continue to be supported.
The REST API follows the REST architectural style and uses resources, HTTP verbs, and status codes. JSON is used for request and response bodies. REST API follows the token based authentication that is supported by BMC Remedy AR System. For more information, see
Login information
. The REST API provides certain endpoints that are aligned with the Swagger specification language.
This section covers the following topics:
HTTP access to the REST API
When you perform a new installation, you must either configure HTTPS or allow REST API access over HTTP. Even though, by default the REST API is only accessible over HTTPS, BMC recommends that you enable access over HTTP for testing purposes. For more information about configuring a REST API through HTTP or HTTPS, see
Configuring the REST API
.
Security considerations
- Enabling the REST API access over HTTP is not recommended in production environment and should only be used for testing purposes.
- REST API requests contain your Authentication token in an HTTP header, and are passed in plain text when using HTTP. If you enable HTTP access to experiment with the REST API, ensure that you revert the configuration.
Authentication and permissions in REST API
You must be BMC Atrium CMDB user to request all endpoints in the REST API. Before processing a request, the REST API authenticates the request to determine the user. For more information about authentication and permissions, see
Login information
.
Using the Swagger UI
REST API are aligned with Swagger specifications. You can generate the REST client using the Swagger tools. You can retrieve the Swagger specifications by using the following REST API link.
/api/v1.0/swagger.json
Alternately, you can also use the following Swagger URL.
https://<host name>:<port number>/cmdb/api/help.html
The Swagger UI enables you to explore and interact with all the endpoints in the REST API.
Calling an endpoint
On the Swagger UI, expand the GET Application Version category and the GET/cmdb/v1.0/version endpoint. Click Try it out! to call the endpoint. A successful request returns the current status of all the BMC Remedy AR System applications. To understand the results structure, click Model in the Response Class section of this endpoint.
Before you try any operations, you must click Authorize at the top-right corner and enter a token prefixed with AR-JWT . For more information, see
Login information
.
Try it out!
The Swagger UI allows you to call any endpoint in the REST API, but does not provide a sandbox for this experimentation. Some endpoints make changes to the state of the CMDB instance. For example, creating a new CMDB instance or deleting a CMDB instance. Call these endpoints from Swagger UI only if you are comfortable with the changes that are made to BMC Atrium CMDB that you are connected to.
Calling the REST API from real clients
The Swagger UI is convenient for experimenting with the REST API. However, for real clients, you can call the REST API from any scripting or programming language that supports HTTP. The following is an example related to the request sent to the /cmdb
endpoint using curl
:
This documentation uses curl
for giving examples of REST API requests. The Swagger UI also shows the equivalent curl
command for requests.
Whatever client language or tool you use to call the REST API, BMC recommends that you read all related topics first to see how to construct valid requests and handle responses.
Comments