Page tree

Skip to end of metadata
Go to start of metadata

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.8 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:

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

Note

To log in to the BDA REST API, you must have a valid username and password.

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://hostname/bda/rest/api/1.0/login

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.

statusstatus_codeError CodeCode Description
success200N/AThe request was fulfilled by the REST API.
failed400Bad RequestThe request is malformed because the format is incorrect, or because the called operation is unsupported.
401UnauthorizedThe user is unauthorized to call the REST API because of invalid credentials.
405Method Not AllowedThe method used to make the request is not allowed by the BDA REST API. The only methods allowed are GET and POST.
500Internal Server ErrorThe REST API call failed because of an unexpected error by the server or the API.

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 reenter the token, 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://hostname/bda/rest/api/1.0/logout

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://hostname/bda/rest/api/1.0/keepalive

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"}

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

 

  • No labels