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:

Code Example

Curl

 curl -X GET --header -H 'Authorization: bearer <your_token>' 'Accept: application/json' 'http://<host name>:<port number>/api/cmdb/versions

Request url

http://<host name>:<port number>/api/cmdb/v1.0/versions

Response Body

{
  "applicationVersions": [
    {
      "applicationId": "AR005056B5170DLd#JSQUZQNEQXRkA",
      "applicationName": "BMC Remedy Action Request System",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "AP00C04FA081BA2Nm_PwBDU0IQQAAA",
      "applicationName": "Approval Server",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "AE00C04F651D06Z2eLPQOYzG6waAIA",
      "applicationName": "Assignment Engine",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "EE005056B5170DJSb7TQBxBdFAhDkK",
      "applicationName": "BMC Remedy Email Engine",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "AI005056B5170D5P4XTA1qFVCQmg4A",
      "applicationName": "BMC Atrium Integrator",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "FN00C04FA081BA420fQwLB8zJA2QAA",
      "applicationName": "Remedy Foundation Prime Elements",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "ID00C04FA081BA5xCWQwIeef8wbQoA",
      "applicationName": "Remedy Foundation Site",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "ID00C04FA081BAyBCWQwW2uf8wbAoA",
      "applicationName": "Remedy Foundation Company",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "ID00C04FA081BA[hCWQwVS[g8wbgoA",
      "applicationName": "Remedy Foundation Product Catalog",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "PD00C04FA081BAm3gnQwfv6cQw_AEA",
      "applicationName": "Remedy Definitive Software Library",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "PD00C04FA081BA0SvxQgaxH66Q1wQA",
      "applicationName": "Product Catalog",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "OB00C04FA081BABZlxQAmyflAg1wEA",
      "applicationName": "BMC Atrium CMDB",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    },
    {
      "applicationId": "AI00C04FA081BARqAsSAwQwppQMToC",
      "applicationName": "Atrium Impact Simulator",
      "majorVer": 9,
      "minorVer": 1,
      "maintenanceVer": 3,
      "patchNum": 0,
      "stage": 0,
      "exist": true
    }
  ]
}

Response Code

Response Headers

{
  "date": "Thu, 04 May 2017 10:23:31 GMT",
  "server": "Jetty(8.1.15.v20140411)",
  "content-length": "2321",
  "content-type": "application/json"
}

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.

Learning about the REST API

REST API versioning

General principles for using BMC Atrium Core REST API

Using the REST API

Using REST APIs with Swagger

Endpoints in the REST API 1