This documentation supports the 19.11 version of BMC CMDB, which is available only to BMC Helix subscribers (SaaS).

To view an earlier version, select the version from the Product version menu.

General principles for using the REST API

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 API are specified using the Swagger specification language.

The following principles are common to the endpoints provided by the BMC Atrium Core REST API.


HTTP verbs

Where possible, endpoints use the following verbs consistently:

VerbPurpose
GETRetrieve a single resource, or collection of resources.
POSTCreate a new resource.

PUT

Update a resource, specifying the required target state of all fields. Any fields omitted are reset to default values or deleted, as appropriate for the endpoint.
PATCHUpdate a resource, specifying the required target state of some fields. Any omitted fields are not modified. To delete a field, set it to null .
DELETEDelete a resource.

Input encoding

When constructing the URL for an endpoint that contains a dynamic portion (either in the path or in the query string), ensure that you correctly encode the characters. For example: 

https://<host name>:<port number>/api/cmdb/v1.0/instances/
https://<host name>:<port number>/api/cmdb/v1.0/instances/{datasetId}/{namespace}/{className}

JSON format

JSON is used for both request and response bodies. If you are editing JSON request bodies manually, you must escape any reserved characters in your strings.

URLs in responses

Several POST endpoints create a new resource, which you can retrieve later using the REST API. In these cases, the response to the POST request contains a "uri" field, containing the URL of the newly created resource.

For example:

curl -X GET --header 'Accept: application/json' --header 'Authorization: <Your token>' 'https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.SAMPLE/BMC.CORE/BMC_ComputerSystem?ids=OIGAA5V0HHE1FAOPM3MZOPM3MZALU9&attributes=Name%2CShortDescription&offset=0&limit=500&dataset_mask=0&num_matches=false'
 
https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.SAMPLE/BMC.CORE/BMC_ComputerSystem?ids=OIGAA5V0HHE1FAOPM3MZOPM3MZALU9&attributes=Name%2CShortDescription&offset=0&limit=500&dataset_mask=0&num_matches=false

HTTP/1.1 200 OK
{
  "instances": [
    {
      "instance_id": "OIGAA5V0HHE1FAOPM3MZOPM3MZALU9",
      "class_name_key": {
        "name": "BMC_ComputerSystem",
        "namespace": "BMC.CORE"
      },
      "attributes": {
        "Name": "instances_CS1",
        "ShortDescription": "n/a"
      },
      "_links": {
        "self": [
          {
            "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.SAMPLE/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHE1FAOPM3MZOPM3MZALU9"
          }
        ]
      }
    }
  ]
}

Pagination 

Several endpoints have the potential to return large amounts of data in their responses. These endpoints follow a standard approach for returning paginated results. For example, a search for all Hosts in the system could find more than the default page limit of 100 results. In this case the endpoint returns the first 100 results, and additional fields that provide links to the next page:

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?offset=0&limit=5&dataset_mask=0&attributes=Name,ShortDescription&num_matches=true'
 
URL: https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem?offset=0&limit=5&dataset_mask=0&attributes=Name,ShortDescription&num_matches=true

HTTP/1.1 200 OK
{
    "instances": [
        {
            "instance_id": "OIGAA5V0HHF21AOP5NOBOP5NOBM5Y9",
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "attributes": {
                "Name": "instances_CS1",
                "ShortDescription": "n/a"
            },
            "_links": {
                "self": [
                    {
                        "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOP5NOBOP5NOBM5Y9"
                    }
                ]
            }
        },
        {
            "instance_id": "OIGAA5V0HHF21AOP5NOBOP5NOBM5YK",
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "attributes": {
                "Name": "instances_CS2",
                "ShortDescription": "n/a"
            },
            "_links": {
                "self": [
                    {
                        "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOP5NOBOP5NOBM5YK"
                    }
                ]
            }
        },
        {
            "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6K",
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "attributes": {
                "Name": "instances_CS1",
                "ShortDescription": "n/a"
            },
            "_links": {
                "self": [
                    {
                        "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6K"
                    }
                ]
            }
        },
        {
            "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6L",
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "attributes": {
                "Name": "instances_CS2",
                "ShortDescription": "n/a"
            },
            "_links": {
                "self": [
                    {
                        "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6L"
                    }
                ]
            }
        },
        {
            "instance_id": "OIGAA5V0HHF21AOPOD1DOPOD1DDL6M",
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "attributes": {
                "Name": "instances_CS3",
                "ShortDescription": "n/a"
            },
            "_links": {
                "self": [
                    {
                        "href": "https://<host name>:<port number>/api/cmdb/v1.0/instances/BMC.ASSET/BMC.CORE/BMC_ComputerSystem/OIGAA5V0HHF21AOPOD1DOPOD1DDL6M"
                    }
                ]
            }
        }
    ],
    "num_matches": 292
}    
 
 

Here, the value of the "offset" field is the starting index of the first item in this page of results. The Default value is 0. The "limit" field defines the number of Instances to be retrieved. The default value is 500. When you the "num_matches" flag is set to true, it returns the number of matching instances. The default value is false.

Error responses

Failed requests are indicated by returned 4xx (client error) or 5xx (server error) HTTP status codes. In some cases the response body might also contain an object that contains details of the error, with the following fields:

FieldMeaning
codeThe HTTP status code.
messageA description of what went wrong.

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid information leakage to the caller. Here is an example request, resulting in the response 400 Bad Request

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://<host name>:<port number>/api/cmdb/v1.0/instances'
{
    "instances": [
        {
            "class_name_key": {
                "name": "BMC_ComputerSystem",
                "namespace": "BMC.CORE"
            },
            "dataset_id": "BMC.ASSET"
            
        }
   ]
} 

HTTP/1.1 400 Bad Request
[
  {
    "messageType": "ERROR",
    "messageText": "No value supplied for a required attribute.",
    "messageNumber": 120076,
    "messageAppendedText": "Name"
  }
]
Was this page helpful? Yes No Submitting... Thank you

Comments