Important

   

This space contains documentation for TrueSight Server Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Server Automation 8.9.

Using the REST APIs

REST API enables developers to integrate data from TrueSight Server Automation with external applications. You can use the APIs to perform Create, Retrieve, Update, and Delete operations (CRUD) on the following TrueSight Server Automation resources: 

  • Patch Catalogs 
  • Patching jobs 
  • RBAC Roles
  • Servers 
  • Groups (Job, Depot, Server (static group), component, component_template groups are supported.)
  • Smart groups 

The API follows the REST architectural style, so resources, HTTPS verbs, and status codes are used. This API uses standard HTTPS GET and POST methods to retrieve data from the server, and all responses from the server are in JavaScript Object Notation (JSON) format. The endpoints provided by the API are specified using the  Swagger  specification language. 

API versions

The REST API is versioned separately from the TrueSight Server Automation. The API version provided with this version of the TrueSight Server Automation is version 1. You can find the version in the URL. 

Syntax:

https://<hostname>:<port>/rest/api/<version>/groups/server

Example:

https://<hostname>:<port>/rest/api/v1/groups/server


Content format

JSON is used for both request and response bodies. Each API request must include the following content-type parameter in the request header: 

accept: application/json

Timestamps

The timestamps for session and error responses are returned in ISO 8601 (YYYY-MM-DDTHH:MM:SS+HH:MM) format. Timestamps in all other response bodies are returned in YYYY-MM-DD HH:MM:SS HH:MM  format. The timestamp displayed is of the Application Server timezone.

JSON Responses

The response body contains the results of all requests. In addition to the requested content, the response body also contains status content that describes the success or failure of the request. 

  • Successful requests are indicated by returned 2xx HTTP status codes. 
  • Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. 

The response body also contains an object that contains details of the error, with the following fields:

Field

Meaning

timestampTime when the exception occurred

status

The HTTP request status code

error

The associated HTTP status message

messageThe error message
pathPath of the endpoint

Error response

Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. 

Here is an example request, resulting in the response 400 Bad Request:

{
  "timestamp": "2019-06-17T07:01:22.481+0000",
  "status": 400,
  "error": "Bad Request",
  "message": "#: required key [group] not found#:
required key [catalog] not found.",
  "path": "/rest/api/v1/patching-jobs/954"
}

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid leaking information to the caller.

Status codes

The following table describes the status codes.

Error Code

Description

200 OKThe request is accepted and results are returned.
201 CreatedA new resource is created after PUT or POST request.
202 AcceptedThe request is accepted for asynchronous processing.
204 No ContentThe request is completed but the server has no data to be displayed.
400 Bad RequestThe request was invalid. Either the URL is incorrect or the application specific constraints are violated.
401 Unauthorized

The client did not provide suitable authorization header. This error might occur in the following conditions:

  • A request to generate a token from /api/about with incorrect credentials, or for a user that has been deactivated.
  • A standard endpoint request that omits a valid, unexpired token.
403 Forbidden

Accessing the page or resource you are trying to reach is forbidden. This error occurs when the user does not have the required permission to perform the requested action.

404 Not FoundThe requested resource is not found.
405 Method not allowedThe method is not allowed by the web server for a requested URL.
500 Internal Server ErrorThe server encountered an unexpected error.


Pagination

Several endpoints have the potential to return large amounts of data in their responses. These endpoints support a common approach for returning paginated results. Use the size request parameter to specify how many results are displayed on one page and thus how results should be returned. Use the page request parameter to specify which page should be returned.

Example:

curl -X GET "https://<hostname>:<port>/rest/api/v1/groups/server?page=4&size=20" -H "accept: application/json" -H "session-id: dbc1da51-2cd1-45a6-ad00-91dbab49bb54"

Here, the size parameter indicates the maximum number of items displayed on one page in the result. The page parameter indicates the page number. 

A paginated response includes a total_records in the response body. This count indicates how many results are available in total, which can aid you in asking for more pages, if, for example, you are implementing user-driven paged list display. Each API response will contain links to previousnextfirst, and the last page.

Unsupported use cases

You cannot perform the following tasks by using the REST APIs provided with TrueSight Server Automation 8.9.04.001: 

  • Use the APIs for Solaris, SUSE, AIX, OEL, Debian operating systems.
  • Create or delete catalogs.
  • Retrieve details of a specific catalog. However, you can retrieve the list of catalogs. 
  • Update catalog definitions or properties.
  • Update properties for servers.
  • Delete patching jobs.
  • Get a list of patching jobs.
  • Set or retrieve job approvals for the jobs.
  • Create or browse smart groups.
  • Browse folders.
  • Enroll or decommission servers.
  • Configure PGC.
  • Create, retrieve, update, or delete users.
  • Create, update, or delete roles.
  • Retrieve details of a specific role. However, you can retrieve the list of all roles.
  • Get details for specific catalogs. However, you can retrieve the list of catalogs. 
  • Copy options for template deploy jobs, pre and post commands for patching jobs.


Was this page helpful? Yes No Submitting... Thank you

Comments