Using the Swagger UI

The BMC Common REST API provides a user-friendly interface to experiment with the REST API calls, known as the Swagger UI. You can make calls to the API from any scripting or programming language that supports HTTP/S, but you can use the Swagger UI from any browser without any programming effort on your part.

To access the Swagger UI

1. In your web browser, enter the URL in the following format:
   https://serverName:portNumber/cra/swagger

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

Authenticating with a token

Requests in the REST API must be authenticated. The authentication mechanism is token-based. The Swagger UI lets you generate a token from the credentials of a valid user of BMC mainframe products who is granted the right to login using web services.

To generate a token

1. In the Swagger UI, open the logon-controller menu and select the Login or Logon endpoint.

   Important

   We recommend using the Login endpoint for security purposes. 

2. Click Try it out.

3. Enter the following parameter:

   Parameter	Description
   serviceName	Name of a service that can be accessed by the API Example: Mva

4. In the request body, provide a username and password as a JSON string as shown in the following example:

   {
     "username": "your user name",
     "password": "your password"
   }
   

   Important

   To use a client certificate, make sure that the request body must not contain any username and password parameters as shown in the following format:

   {

   }

5. Click Execute.
   The API returns a response. In the response body there is user token that looks something like this:

   {
   "userToken": "06f50386-bb0f-4090-b46b-32106ed19844"
   }
6. Copy the token (only the string within the quotation marks).
7. Scroll to the top of the page and click Authorize.

8. In the Value field, type Bearer followed by the pasted string.

   Bearer 06f50386-bb0f-4090-b46b-32106ed19844
   

9. Click Authorize.
   You can now use all of the endpoints. The token remains valid for the amount of time set in the timeout value after the last activity performed using the API. The default for the timeout is 15 minutes. For details about changing the value, see Installing-and-configuring-the-Common-REST-API.

10. Click Close.

    Important

    If you click Logout, your session closes, and you will require a new authentication token.

Calling an endpoint

Now you can make your first explicit API request. For example, you can use the views endpoint to get a list of views that are available for the product, or you can use data endpoint to retrieve the data for a specific view. See the documentation for each endpoint for details about the parameters.

Calling the API from real clients

The Swagger UI is convenient for experimenting with the REST API. However, for real clients, calls to the API can be made from any scripting or programming language that supports HTTP/S. Whatever client language or tool you use to call the API, it is recommended you read the related documentation first to see how to construct valid requests and handle responses.  See the topics in Common-REST-API-data-endpoints for more details on using the endpoints of the API.