REST API versioning

The REST API is versioned separately from BMC Discovery. The API version is of the format major.minor. The REST API was first released in BMC Discovery 11.1 with API version 1.0; BMC Discovery 11.2 has API version 1.1. Further versions of the API will be available with future product releases, but an API version will never be withdrawn. This means multiple concurrent API versions will be supported by a given Discovery version.

To determine the versions of the API supported by a BMC Discovery version, use the /api/about endpoint. This returns a list of API versions and product information:

curl https://appliance/api/about


{
    "api_versions": [
        "1.0",
        "1.1"
    ],
    "component": "REST API",
    "product": "BMC Discovery",
    "version": "12.0"
}

Note that this endpoint does not perform authentication checks, so does not require a token to be passed and can also be accessed in a browser if required.

New API versions will always be backwards compatible, so a program written against one version of the API will behave identically if run against a later version. New API versions may contain:

Endpoints not present in earlier versions.
Extensions to existing endpoints, made in a backwards compatible way. Typically endpoints will be extended by supporting additional optional query parameters, whose absence will maintain the old behavior.

To see what features are available in each of the supported API versions, view the version-specific swagger file. Alternatively, see see the list of endpoints available in the latest version of the API.

Note

With the introduction of data sources,in BMC Discovery version 20.02 (12.0),credential types have been recategorized. Existing searches using the REST API might no longer provide the same results as in previous versions. You can use the REST API listing to determine the credential categories for your credentials:

GET /vault/credential_types

The documentation for individual endpoints explains which version of the API an endpoint was introduced or extended in.

Once you have chosen an API version to use, include the version in the URL for every endpoint you call. Here are some example URLs for v1.0 of the API:

https://appliance/api/v1.0/vault/credentials
https://appliance/api/v1.0/data/kinds/Host
https://appliance/api/v1.0/knowledge/status

An endpoint is considered to contain a defect if it does not behave as documented or if it suffers from poor performance, for example. The defect may be fixed in a future BMC Discovery patch release, with no new REST API version issued. The release notes for the patch will describe the fix.

REST API versioning

Comments