Trying out the REST APIs

Swagger is a set of libraries that allows developers of a REST-based service to provide documentation and testing tools to client-side developers in an automated way. The endpoints offered by the REST API can be viewed on their own page. However, they are also documented in a more structured way using the  Swagger specification language , which is embedded in the system itself.

You can use the Swagger UI to interactively explore the REST API. Calls to the REST API can be made from any scripting or programming language that supports HTTPS, but the Swagger UI can be used from any browser without any programming effort on your part. 

Also, you can test the REST API from a client utility, such as Postman. BMC does not advocate using one client utility over the other. 

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

In order to use the REST API over HTTPS, you must specify the port number that corresponds to your security. The default port is 9843.

To access the Swagger UI

Do the following:

1. Start your web browser.

2. Enter the URL in the following format: 

   Syntax:

   https://<hostname>:<port>/rest/apidocs

   Example:

   https://automation01:9843/rest/apidocs
   

3. (Optional) For future reference, bookmark this URL.

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 username, 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 execute 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.

Related topics

REST API endpoints

Examples of REST APIs