Using REST API
This topic provides instructions to log in to the RESTful web services and reference information for all REST API calls supported by the application.
BMC Helix Automation Console provides REST API endpoints to perform all tasks currently supported by the application.
The API follows the REST architectural style and uses resources, HTTP verbs, and status codes. JavaScript Object Notation (JSON) is used to represent data structures in request and response bodies. All endpoints (except the Login API) use the OAuth 2.0 protocol for authentication.
Calling the API
Calls to the API can be made from any scripting or programming language that supports HTTPS. Whatever client language or tool you use to call the REST API, it is recommended you read the related documentation first to see how to construct valid requests and to handle responses.
Requests to all endpoints in the REST API must be on behalf of a BMC Helix Automation Console user. Before processing a request, the API authenticates the request to determine the user. After successful authentication of a user, endpoints check whether the user has permission to perform the requested action. Users must be granted the same rights as if they were attempting the action through the equivalent user interface or command line tool. If the user lacks the required right, a 403 Forbidden status code is returned by the endpoint.
Login API
To interact with BMC Helix Automation Console REST API, you must log in and obtain the authentication token.
Request
HTTP method: POST
Request URL: https://<BMC Helix Automation Console URL>/api/v1/sessions
Example: https://<customerprefix>-xxx.onbmc.com/api/v1/sessions
Request body properties
Property | Description |
|---|---|
username | Specifies the username required to log on to the Automation Console. |
password | Specifies the password that matches the username, in a base-64 encoded format. |
Example request
"username": "BLAdmin",
"password": "<password>"
}
Response
If successful, a session is created for the current user.
Sample response
"token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJCTEFkbWluQGRlZmF1bHR0ZW5hbnQudHNzYSIsIkF1dGhvcml0aWVzIjo
iUk9MRV9BRE1JTiIsImlhdCI6MTU0NTA0NDY0NSwiaXNzIjoid3d3LmJtYy5jb20iLCJleHAiOjE1NDUwNjI2NDV9.
NBWTXJpHeIDcEyIDIJ3iq6jbWgXIvxBqtvzB1z_s0vE"
}
A session is created successfully. You can now execute any API calls.
Get Session API
Gets the details of the current session.
Request
HTTP method: GET
Request URL: https://<BMC Helix Automation Console URL>/api/v1/sessions
Request body: No parameter
Response
Code | Description |
|---|---|
200 | OK |
401 | Unauthorized |
500 | Internal Server Error |
Sample response
"user": {
"name": "BLAdmin",
"securityGroups": [
{
"id": "cd41cedbb-a981-4a46-b658-29a5a3837077",
"name": "BLAdmin",
"description": "This is admin for TSSA",
"role_name": "BLAdmins",
"default_job_path": "/test/jobs",
"default_depot_path": "/test/depot",
"creation_date": "2019-04-08 10:50:44.037702",
"modification_date": "2019-04-08 10:50:46.037702",
"site": {
"name": "172.25.150.238",
"port": 9843,
"siteType": "TSSA",
"serverHost": "<host_ip_address>"
}
}
],
"admin": true
},
"site": {
"siteId": "a539084a-1893-4a75-8892-24bee1a8f291",
"name": "POS-VM2.bmc.com",
"serverHost": "POS-VM2.bmc.com",
"port": 9843,
"protocol": "https",
"adminRole": "BLAdmins",
"siteType": "TSSA",
"workerId": "tssa-connector",
"buildVersion": "8.9.03.162",
"fqUserSuffix": "defaulttenant.tssa",
"description": "string",
"primarySite": true
},
"tenant": {
"id": 1,
"name": "defaulttenant"
},
"active_security_group": {
"id": "cd41cedbb-a981-4a46-b658-29a5a3837077",
"name": "BLAdmin",
"description": "This is admin for TSSA",
"role_name": "BLAdmins",
"default_job_path": "/test/jobs",
"default_depot_path": "/test/depot",
"creation_date": "2019-04-08 10:50:44.037702",
"modification_date": "2019-04-08 10:50:46.037702",
"site": {
"name": "172.25.150.238",
"port": 9843,
"siteType": "TSSA",
"serverHost": "<ip_address>"
}
}
}
Delete Session API
Logs out and deletes the current session.
Request
HTTP method: DELETE
Request URL: https://<BMC Helix Automation Console URL>/api/v1/sessions
Request body: No parameter
Response
Code | Description |
|---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
500 | Internal Server Error |
Where to go next?
For references to all REST API calls included in this release, see the following topics: