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 CMDB REST API.

Endpoint verbs

Where possible, endpoints use the following verbs consistently:

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 use the escape syntax for any reserved characters in your strings to avoid breaking the manually entered code. For information about JSON syntax for qualification, see the JSON online documentation. 

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"
          }
        ]
      }
    }
  ]
}