Using the TSWS REST API to integrate TrueSight data with other products

The TrueSight Web Service (TSWS) API enables developers to integrate data from the TrueSight Presentation Server with external applications. This API uses standard HTTP GET and POST methods to retrieve data from the server, and all responses from the server are in JSON format. Although REST API messages are sent and received using HTTP, BMC recommends that you implement REST using HTTPS for increased security. This security is important if the client passes sensitive information, such as authentication credentials over the network.

With the exception of the login and tenant endpoints, all of the TSWS REST API endpoints require the presence of the TrueSight Infrastructure Management component.

Related topics

Adding and editing components

Prerequisites

Installation of the following TrueSight Operations Management components:
- TrueSight Presentation Server
- TrueSight Infrastructure Management
Installation of a client utility, such as Postmam

API versions

The REST API is versioned separately from the TrueSight Presentation Server. The API version provided with this version of the TrueSight Presentation Server is version 10.0. As necessary, newer versions of the API will be released with future product releases.

JSON format

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

content-type application/json

Timestamps

All timestamps in response bodies are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SS+HH:MM

Endpoints

The following table contains the endpoints in the TSWS REST API.

Endpoint	Verb	Endpoint purpose
`login`	POST	Obtains the authToken required to perform all other operations. For more information, see TSWS authentication.
`configdata`	POST	Retrieves configuration data of monitor instances. For more information, see Retrieving the configuration data of monitor instances.
`perfdata`	POST	Retrieves performance data of monitor instances. For more information, see Retrieving the performance data of monitor instances.
`devices`	GET	Retrieves a list of monitored devices. For more information, see Retrieving the list of devices.
`instances`	GET	Retrieves a list of monitored instances. For more information, see Retrieving the list of monitor instances.
`monitortypes`	GET	Retrieves a list of monitor types. For more information, see Retrieving the list of monitor types.
`tenants`	GET	Retrieves a list of tenants. For more information, see Retrieving the list of tenants.

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
statusCode	The HTTP request status code
statusMsg	A description of the request statusCode
responseMsg	Status of the response
responseContent	Portion of the response that contains the specified content For unsuccessful requests, this field can also provide some detail or `null`.

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

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://appliance/api/v1.0/data/search?query=SEARCH%20Host&offset=-1' HTTP/1.1 400 Bad Request { "code": 400, "message": "'offset' cannot be negative", "transient": false }