Trying out the REST API call methods

You can call the REST API using the Swagger UI or from real clients. Review or follow the steps outlined in this topic to learn how you can use either approach to successfully make calls to the BMC Atrium Core REST API.

How you can use REST API to integrate an external application

Calling the REST API from the Swagger UI

Configure HTTPS
Call the REST API from the Swagger UI

Calling the REST API from the real clients

Configure HTTPS
Call the REST API from the real clients

To configure HTTPS

On BMC Atrium Core you must either configure HTTPS or allow API access over HTTP. Either approach will work for this evaluation exercise, though enabling access over HTTP is only recommended for testing purposes.

Consider the following security implications

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 you use HTTP. If you enable HTTP access to experiment with the REST API, ensure that you revert the configuration.

To call the REST API from the Swagger UI

You can generate the REST client using the by 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.

Authenticate with a token from the Swagger UI

Requests to every endpoint in the REST API must be made on behalf of a BMC Atrium CMDB user. The authentication mechanism is token-based, but the Swagger UI enables you to generate a token from the credentials of a valid BMC Atrium CMDB user. For more information about user roles and permissions, see Roles and permissions Open link .

When you know that your user has the api-access permission, click Authorize in the top right of the Swagger UI to display the Available Authorizations dialog box:

Generate a token from any REST client by using the POST method. Add the token to the Authorization screen; then click Authorize to return to the main Swagger UI page. A token is now requested in the background and is added to each subsequent endpoint request. To learn more about authentication and tokens, see Login information Open link .

Call an endpoint from Swagger

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.

Note

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 Open link .

Important

Through 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 to which you are connected.

To call 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 relates 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.

Regardless of the client language or tool you use to call the REST API, BMC recommends that you first read all related topics to see how to construct valid requests and handle responses.