Introduction to the REST API
The REST API is intended to be used by a script or program to interact with and control a BMC Discovery appliance from a remote machine. You can use the API for a variety of tasks, such as:
- Submitting discovery runs
- Managing credentials
- Querying the data in your system
- Uploading TKUs
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.
By default the API is only accessible over HTTPS. On a new appliance you must either configure HTTPS or allow API access over HTTP. Either approach will work for this topic, though enabling access over HTTP is only recommended for testing purposes.
Enabling REST API access over HTTP is not recommended in production and should only be used for testing purposes. API requests contain your Authentication token in an HTTP header, and are passed in plain text when using HTTP. If you enable HTTP access to experiment with the API, do not forget to revert the configuration.
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 Help and 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 the Authentication and permissions in the REST API topic.
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.
Try it out!
The Swagger UI allows you to call any endpoint in the REST API, but does not provide a sandbox for this experimentation. Some endpoints make changes to the state of the appliance - for example, creating a new discovery run or deleting a credential. Only call these endpoints from the Swagger UI if you are happy for the changes to be made on the appliance you are connected to.
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.