Using the REST APIs

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

You can use the BMC Helix 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 API is to enable you to perform most tasks that you can currently do through the BMC Helix Discovery UI. 

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 Helix Discovery Swagger UI

To access the BMC Helix DiscoverySwagger UI, from any page in the BMC Helix 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:

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 Helix Discovery user. The authentication mechanism is token-based. You can use a token generated from the BMC Helix Discovery Users administration page for users with the api-access permission. The BMC Discovery Outpost also supports JWT tokens that are generated from BMC Helix Portal.

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.

Enter your BMC Helix 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

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 /discovery endpoint, using curl, looks like:

curl -i -X GET -H 'Authorization: Bearer <your_token>' 'https://instance/api/v1.9/discovery'

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

Similarly from the BMC Discovery Outpost, a request to the /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. 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.