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": "11.2"
}

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 the list of endpoints available in the latest version of the API. 

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