REST API versioning

The REST API is versioned separately from BMC Helix Discovery. The API version is of the format major.minor. The BMC Helix Discovery REST API was first released in BMC Discovery 11.1 with API version 1.0; BMC Discovery 11.2 had API version 1.1, and so on.

The BMC Discovery Outpost REST API was first released in BMC Helix 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 Helix Discovery version, use the /api/about endpoint. This returns a list of API versions and product information:

curl https://helix-discovery-instance/api/about  {
    "product": "BMC Helix Discovery",
    "component": "REST API",
    "version": "DaaS",
    "api_versions":
    [
        "1.0",
        "1.1",
        "1.2",
        "1.3",
        "1.4",
        "1.5",
        "1.6",
        "1.7",
        "1.8",
        "1.9",
        "1.10",
        "1.11",
        "1.12"
    ],
    "product_version": "24.1.02"
}

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:

curl https://outpost/api/about  {
  "product": "BMC Discovery Outpost",
  "component": "REST API",
  "version": "13.2.0.1",
  "api_versions": [
    "1.0",
    "1.1",
    "1.2",
    "1.3",
    "1.4",
    "1.5",
    "1.6",
    "1.7",
    "1.8",
    "1.9",
    "1.10",
    "1.11",
    "1.12"
  ],
  "product_version": "24.1.02"
}

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

Note

With the introduction of data sources,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.10 of the API:

https://helix-discovery-instance/api/v1.12/vault/credentials
https://helix-discovery-instance/api/v1.12/data/kinds/Host
https://helix-discovery-instance/api/v1.12/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 Helix Discovery update, with no new REST API version issued. The release notes for the patch will describe the fix.

REST API versioning

Comments