Trying out the REST APIs

Process overview

Perform the following steps to call the REST API from either Swagger UI:

1. Configure HTTPS access
2. Access the Swagger UI
3. Obtain the authentication token
4. Authorize the session
5. Call an endpoint from the Swagger user interface

To configure HTTPS access

To use the REST API over HTTPS, specify the port number corresponding to your security. The default port is 9843.

To access the Swagger UI

1. In a web browser, enter the following URL:
   https://<hostname>:<port>/rest/apidocs
   For example, https://automation01:9843/rest/apidocs
2. (If you are using a load balancer environment) Enter the following URL for the load balancer:
   https://<loadbalancerHost>:<loadBalancerPort>/rest/apidocs

This launches the Swagger UI, which enables you to explore and interact with all endpoints in the REST API. 

To obtain the authentication token

Requests to every endpoint in the REST API must be made on behalf of a TrueSight Server Automation user. The authentication mechanism is session-based. The Swagger UI lets you generate a session from the credentials of a valid TrueSight Server Automation user who is granted the right to login using web services. 

1. In the Swagger UI, click the Sessions link.
2. Under Sessions, click Post.
   
    
3. Click Try it out.
4. In the Parameters section, enter the TrueSight Server Automation user name, password, role, and authentication type.
5. A session is now requested in the background. The session_id attribute in the Response Body section contains the generated session ID, which you can use for authentication in subsequent requests.
   
   
   
   

To authorize the session

After obtaining the session ID, you must authorize the session. Do the following:

1. In the top-right corner, click Authorize.
2. Use one of the following authentication methods:
   
   
   
   
   • Authorization (apiKey)
     In the Value field, enter the authorization header or the Remedy Single Sign-On token, and click Authorize. For information about obtaining the Remedy Single Sign-On token, see Implementing Remedy Single Sign-On Authentication.
   • api-key (apiKey)
     This authentication method is deprecated. BMC recommends using the authorization header.
   • api-role (apiKey)
     In the Value field, enter the user role and click Authorize. By default, the value of the default_role attribute of POST: /api/v1/sessions API response is used.
3. Click Close.

To call an endpoint from Swagger

After authorizing the session, you can run subsequent requests. 

1. To try out other endpoints, such as servers, expand the applicable section and click on the method.
2. To access the request parameter input fields, click Try it out. 

3. Enter the request parameters, and click Execute.

   Try it out!

   The Swagger UI enables you to call any endpoint in the REST API, but it does not provide a sandbox for this experimentation.

To download a copy of the REST API to a local system

If you prefer to experiment with a local copy of the API, you can click the file name at the top of the page to open the file in a text editor.