REST API versioning
The REST API is versioned separately from BMC Discovery. The API version is of the format major.minor. The BMC Discovery REST API was first released in BMC Discovery 11.1 with API version 1.0; BMC Discovery 11.2 has API version 1.1.
The BMC Discovery Outpost REST API was first released in BMC Discovery 22.2 (12.5).
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:
{
"api_versions": [
"1.0",
"1.1",
"1.2",
"1.3",
"1.4",
"1.5"
],
"component": "REST API",
"product": "BMC Discovery",
"version": "12.5"
}
To determine the versions of the API supported by a BMC Discovery Outpost version, use the /api/about endpoint. This returns a list of API versions and product information:
{
"api_versions": [
"1.0"
],
"component": "REST API",
"product": "BMC Discovery Outpost",
"version": "12.5"
}
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.
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/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.