(SPE2104)

Getting started

You can access API only over HTTP/S. This topic explains how to submit your first request to the REST API.

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: 

2. https://serverName:portNumber/cra/swagger

   https://cra_host_name:2525/cra/swaggerThis 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 Logon endpoint.
2. Click Try it out.

3. Enter the following parameters:

   Parameter	Description
   password	A valid password
   serviceName	Name of a service that can be accessed by the API Example: Mva
   username	A valid username that goes with the password you entered

4. 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"
   }
5. Copy the token (only the string within the quotation marks).
6. Scroll to the top of the page and click Authorize.

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

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

8. 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 Modifying CRA Properties.

9. Click Close.

   Note

   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.