Using the REST APIs

The BMC Discovery REST APIs are intended to be used by a script or program to interact with and control BMC Discovery or BMC Discovery Outpost from a remote machine.

You can use the BMC Discovery API for a variety of tasks, such as:

• Submitting discovery runs
• Managing credentials
• Querying the data in your system
• Uploading TKUs

You can use the BMC Discovery Outpost API to manage credentials.

The aim of the APIs 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 APIs 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.

Accessing the BMC Discovery Swagger UI

To access the BMC DiscoverySwagger 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:

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.

Accessing the BMC Discovery Outpost Swagger UI

To access the BMC Discovery Outpost Swagger UI, from any page in the BMC Discovery Outpost  UI, click the Settings icon and then the REST API link:

This launches the Swagger UI, which enables you to explore and interact with all endpoints in the BMC Discovery Outpost 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 BMC Discovery 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.

The BMC Discovery Outpost Swagger UI only permits authentication with a token rather than a username and password, see Authentication and permissions in the REST API for more information.

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 -i -X GET -H 'Authorization: Bearer <your_token>' 'https://appliance/api/v1.9/discovery'

HTTP/1.1 200 OK
{
    "running": false,
    "status": "running"
}

Similarly, a request to the BMC Discovery Outpost /vault/credential_types endpoint, using curl, looks like:

curl -i -X GET -H 'Authorization: Bearer <your_token>' 'https://outpost/api/v1.9/vault/credential_types'

HTTP/1.1 200 OK
[
  {
    "categories": [
      "Network Device Credentials",
      "Management Controller Credentials",
      "Storage Device Credentials"
    ],
    "description": "These credentials are used for discovery of Network Device, Printers and other devices",
    "groups": [
      "SCANNING"
    ],
    "label": "SNMP",
    "name": "snmp",
    "uri": "https://outpost/api/v1.0/vault/credential_types/snmp"
  },
...	

...
  {
    "categories": [
      "Storage Device Credentials"
    ],
    "description": "These credentials are used for discovery of Storage devices",
    "groups": [
      "SCANNING"
    ],
    "label": "WBEM",
    "name": "wbem",
    "uri": "https://outpost/api/v1.0/vault/credential_types/wbem"
  },
  {
    "categories": [
      "REST API Credentials",
      "Storage Device Credentials"
    ],
    "description": "These credentials are used for discovery of Nimble devices that use Nimble Web API with token authentication",
    "groups": [
      "SCANNING"
    ],
    "label": "Nimble Storage Web API",
    "name": "web_nimble_auth",
    "uri": "https://outpost/api/v1.0/vault/credential_types/web_nimble_auth"
  }
]

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.