Using REST API

The following sections provide information regarding using a REST API to perform functions in BMC Database Automation (BDA):

Introduction to REST API in BDA

BDA 8.9 uses a representational state transfer (REST) API for invoking functionality. The API enables you to programmatically trigger BDA workflows from other applications and perform management tasks relating to the following functions:

• Compliance
• Actions
• Patching (NEW IN 8.9.03)

REST API requirements

To use the REST API, you must meet the following prerequisites:

• All REST API requests must use the HTTPS protocol.

• Before you can use the API, you must set the following parameter in /app/clarity/dmanager/etc/mtd.conf:

  auth_mode=authentication

  and then restart the mtd service using the following command:

  service mtd restart

For more information regarding user authentication and the auth_mode=authentication parameter, see API infrastructure.

REST API workflow

1. (User) Send the authentication request with a valid username and password in the http header to log in to the API.
2. (BDA REST API) Validate the credentials and send a response with a token in the http header.
3. (User) Preserve the token and send it with every subsequent REST API request.
4. (User) If necessary, send a keepalive request to extend the authentication period of the token. The token expires within 15 minutes of inactivity.
5. (User) Send a logout REST API request to end the session.

The components of this workflow are described in the following sections.

REST API authentication

The BDA REST API uses token-based authentication to authenticate users. Token-based authentication is stateless and the server does not store any information about the user on the server or in a session.

Logging in to the REST API

You can send a login request to log in to the REST API. A valid username and password is sent to the API in the request header when you make the login request. If the request is successful, the API sends back the  x-auth-token value in the header with a response that contains the request status. You must then parse the response header and extract the authorization token value from the header to send it with any future API request.

Syntax

https://<ManagerHostName>/bda/rest/api/api/1.0/login

Method

GET

Required parameters

None

Optional parameters

None

Response

{
  "status": "success",
  "status_code": "200"
}

Example

$ curl -H "username: sysadmin" -H "password:sysadmin" -k -D - https://my.bda.manager.com/bda/rest/api/1.0/login
 
HTTP/1.1 200 OK
Date: Wed, 27 Jan 2016 18:22:24 GMT
Server: Apache
Access-Control-Allow-Orgin: *
Access-Control-Allow-Methods: *
x-auth-token: b4c37d824039a5f87244e17ba0d1df05
Content-Length: 40
Content-Type: application/json; charset=UTF-8
 
{"status":"success","status_code":"200"}

REST API responses

For each request sent, the REST API returns a response in JSON containing both status (success or failed), and status code (number that indicates the reason for the status).

For a status of "failed", the API returns a corresponding error code. For a status of "success", the status code is followed by the requested data (there are no error codes).

The following table describes the status and the corresponding HTTP status codes that the API returns.

REST API token

All REST API requests require a token so that the API can validate the request, The token expires within 15 minutes of inactivity. After that time, you must enter the token again, or you can manage how tokens expire using one of the following methods.

Logout request

You can send a logout request to log out of the REST API and force the token to expire and end the session. The request header must contain the parameter x-auth-token and that parameter must be set to the value obtained from the login request.

Syntax

https://<ManagerHostName>/bda/rest/api/1.0/logout

Method

GET

Required parameters

None

Optional parameters

None

Response

{
  "status": "success",
  "status_code": "200"
}

Example

$ curl -k -H "x-auth-token: b4c37d824039a5f87244e17ba0d1df05" https://my.bda.manager.com/bda/rest/api/1.0/logout
{"status":"success","status_code":"200"}

Keepalive request

You can send a keepalive request to extend the authentication period of the token. The request header must contain the parameter x-auth-token and that parameter must be set to the value obtained from the login request.

Syntax

https://<ManagerHostName>/bda/rest/api/1.0/keepalive

Method

GET

Required parameters

None

Optional parameters

None

Response

{
  "status": "success",
  "status_code": "200"
}

Example

$ curl -k -H "x-auth-token: b4c37d824039a5f87244e17ba0d1df05" https://my.bda.manager.com/bda/rest/api/1.0/keepalive
{"status":"success","status_code":"200"}

Job Status request

You can send this request to retrieve information about the status of a job.

Syntax

https://<ManagerHostName>/bda/rest/api/1.0/jobs/{job_id}

Method

GET

Required parameters

None

Optional parameters

None

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
             "id": "319",
             "title": "Apply Oracle Patch QA STD - Oracle 12.1.0.2 Generic Patch for Linux",
             "status": "Verification Failed",
             "start_time": "24",
             "end_time": "",
             "start_time_display": "12-31-1969 19:00:24",
             "end_time_display": "",
             "error_message": "",
             "description": "",
             "user": "sysadmin",
             "user_ip": "172.19.19.221",
             "domain": "",
             "nodes": [{
                         "id": "43808f6bd4be31bf",
                         "ip": "172.19.18.80",
                         "hostname": "my.bda.manager.com"
                       }]
          }
}

Example

curl -k -H "x-auth-token: ad7aaa89fbf0ef648ddd1607007e819f" https://my.bda.manager.com/bda/rest/api/1.0/jobs/319

Where to go next

After your authentication has been successful and you are logged in to the API, you can begin entering commands to perform the following BDA functions:

Actions

Compliance Standards

Patching