Using the REST API

The aim of the API is to enable you to perform most tasks that you can currently do through the BMC Discovery UI or command line utilities. The XML and CSV export APIs are still supported, but the REST API provides more control when retrieving data, and a range of features across its endpoints.

The API follows the REST architectural style, so resources, HTTP verbs, and status codes are used. JSON is used for request and response bodies. The endpoints provided by the API are specified using the Swagger specification language. All endpoints use the OAuth 2.0 protocol for authentication.

This topic explains how to submit your first request to the REST API.

HTTPS

The API is only accessible over HTTPS.

Using the Swagger UI

Calls to the REST API can be made from any scripting or programming language that supports HTTP. However, this topic starts with a user interface to the API called Swagger UI. To access the Swagger UI, from any page in the BMC Discovery UI, click the Help  icon and then the REST API link:


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

Authenticating with a token

Requests to every endpoint in the REST API must be made on behalf of a BMC Discovery user. The authentication mechanism is token-based, but the Swagger UI lets you generate a token from the credentials of a valid BMC Discovery user. This can be any local or LDAP user, but the user must have the api-access permission. For local users, your administrator can grant this permission on the Users administration page.

For LDAP users, your administrator can use group mapping.

Once your user has the api-access permission, click "Authorize" in the top right of the Swagger UI to display the "Available Authorizations" dialog:

Enter your BMC Discovery username and password in the "OAuth 2.0" section of this dialog. Then click Authorize to return to the main Swagger UI page. A token is now requested in the background and added to each subsequent endpoint request. To find out more about authentication and tokens, see Authentication-and-permissions-in-the-REST-API.

Calling an endpoint

Now you can make your first explicit API request. Expand the "discovery" category and the GET /discovery endpoint. Then click "Try it out!" to call the endpoint. A successful request will return the current status of the discovery system. To understand the results structure, click "Model" in the Response Class section of this endpoint:

If you experience problems calling the endpoint, see the Troubleshooting-the-REST-API topic. Otherwise, you can now experiment with any of the other endpoints.

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. An extremely simple example is the command line tool curl. A request to the same /discovery endpoint as above, using curl, looks like:

curl is used for example API requests in other topics in this section.

The Swagger UI also shows the equivalent curl command for requests:

Whatever client language or tool you use to call the REST API, it is recommended you read all related topics first to see how to construct valid requests and handle responses.