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 TrueSight Server Automation resources. For more information, see REST-API-endpoints.

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.

The REST APIs and Swagger UI support is available in TrueSight Server Automation 8.9.04.001 or later versions.

API versions

The REST API is versioned separately from the TrueSight Server Automation. The API version provided with this version of the TrueSight Server Automationis 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
timestamp	Time when the exception occurred
status	The HTTP request status code
error	The associated HTTP status message
message	The error message
path	Path 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 OK	The request is accepted and results are returned.
201 Created	A new resource is created after PUT or POST request.
202 Accepted	The request is accepted for asynchronous processing.
204 No Content	The request is completed but the server has no data to be displayed.
400 Bad Request	The 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 Found	The requested resource is not found.
405 Method not allowed	The method is not allowed by the web server for a requested URL.
500 Internal Server Error	The 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 previous, next, first, and the last page.