General principles for using the REST APIs

This topic describes the principles common to the endpoints provided by the BMC Helix Discovery and BMC Discovery Outpost REST APIs.

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 fields omitted 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 you correctly encode characters that are not permitted in a URL. For example:

https://appliance/api/v1.12/data/search?query=search%20Host
https://appliance/api/v1.12/knowledge/My%20Pattern%20Upload?activate=true

An encoding reference is available here.

Similarly, if you are editing JSON request bodies by hand, you must escape any reserved characters in your strings.

JSON

JSON is used for both request and response bodies.

Timestamps

All timestamps in response bodies are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SS+HH:MM

Timeouts

All REST requests are subject to a timeout of ten minutes. The timeout duration cannot be changed. The following error message is returned if a request reaches this timeout:

{
  "message"   : "Service currently unavailable",
  "code"      : 502,
  "transient" : true
}

See Error responses for more information on the fields in error responses.

Output 

The REST API sends its output in a compact JSON format, for efficient generation of the response, and use of bandwidth. Some endpoints such as data/search and topology/nodes can produce very large responses.

When you are testing queries, and need to read the response, use the query parameter json_format=pretty that gives pretty-printed output, with 2 spaces for each indent level. The json_format=pretty parameter is accepted by all endpoints.

For example:

curl -i -X GET -H 'Authorization: bearer zX2VMbG...E1MDgzZ' 'https://appliance01.bmc.com/api/v1.12/data/search?query=SEARCH%20Host'

HTTP/2 200 
[{"kind":"Host","count":259,"offset":0,"headings":["name","os","vendor","virtual","partition","cloud","#InferredElement:Inference:Associate:DiscoveryAccess.endpoint"],"results":[["dhcp-172-19-129-100","Oracle Linux Server release 9.3","VMware, Inc.",true,null,null,"172.19.129.100"],["dhcp-172-19-129-104","Red Hat Enterprise Linux Server release 7.9 (Maipo)","VMware, Inc.",true,null,null,"172.19.129.104"],["dhcp-172-19-129-111","Oracle Linux Server release 9.3","VMware, Inc.",true,null,null,"172.19.129.111"],["dhcp-172-19-129-114","Oracle Linux Server release 9.2","VMware, Inc.",true,null,null,"172.19.129.114"],["dhcp-172-19-129-126","Oracle Linux Server release 9.3","VMware, Inc.",true,null,null,"172.19.129.126"],["dhcp-172-19-129-131","Oracle Linux Server release 9.2","VMware, Inc.",true,null,null,"172.19.129.131"],["dhcp-172-19-129-138","Oracle Linux Server release 9.3","VMware, 
data/search?query=SEARCH+Host&results_id=SG9zdABuFtHYZQIAAAEAAAAWYQ%3D%3D&offset=100","results_id":"SG9zdABuFtHYZQIAAAEAAAAWYQ=="}]


curl -i -X GET -H 'Authorization: bearer zX2VMbG...E1MDgzZ' 'https://appliance01.bmc.com/api/v1.12/data/search?query=SEARCH%20Host&json_format=pretty'  

HTTP/2 200
[
  {
    "kind": "Host",
    "count": 259,
    "offset": 0,
    "headings": [
      "name",
      "os",
      "vendor",
      "virtual",
      "partition",
      "cloud",
      "#InferredElement:Inference:Associate:DiscoveryAccess.endpoint"
    ],
    "results": [
      [
        "dhcp-172-19-129-100",
        "Oracle Linux Server release 9.3",
        "VMware, Inc.",
        true,
        null,
        null,
        "172.19.129.100"
      ],
...      
      [
        "dhcp-172-19-132-81",
        "Oracle Linux Server release 9.3",
        "VMware, Inc.",
        true,
        null,
        null,
        "172.19.132.81"
      ]
    ],
    "next_offset": 100,
    "next": "https://'https://appliance01.bmc.com/api/v1.12/data/search?query=SEARCH+Host&results_id=SG9zdABuFtHYZQIAAAEAAAAWZg%3D%3D&offset=100",
    "results_id": "SG9zdABuFtHYZQIAAAEAAAAWZg=="
  }
]

URLs in responses

Several POST endpoints create a new resource, which can later be retrieved using the 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 -i -X POST -H 'Authorization: bearer <your_token>' -d '{
   "ranges": [
     "137.72.95.*"
   ],
   "label": "Scan this"
}' https://appliance/api/v1.12/discovery/runs

HTTP/1.1 200 OK
{
  "uri": "https://appliance/api/v1.0/discovery/runs/728f0458da074bb60e0ee2f06e446973636f7665727952756e",
  "uuid": "728f0458da074bb60e0ee2f06e446973636f7665727952756e"
}

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 one hundred. In this case the endpoint returns the first one hundred results, and additional fields which provide links to the next page:

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://appliance/api/v1.12/data/search?query=SEARCH%20Host'

HTTP/1.1 200 OK
[
  {
    "count": 2446,
    "headings": [...],
    "kind": "Host",
    "next": "https://appliance/api/v1.0/data/search?results_id=SG9zdABuco8EWAIAB9oAAAV84w%3D%3D&query=SEARCH+Host&offset=100",
    "next_offset": 100,
    "offset": 0,
    "results": [ <first 100 results> ],
    "results_id": "SG9zdABuco8EWAIAB9oAAAV84w=="
  }
]

Here, the value of the "offset" field is the starting index of the first item in this page of results (zero-based), "next_offset" contains the index at the start of the next page, and "results_id" is an opaque token which must be passed back to the endpoint when requesting subsequent pages of results. As a convenience, the full URL of the next page is also provided in the "next" field (although paginated results do not necessarily need to be traversed in page order).

The results format is actually a list of objects, where each object represents results for a particular node kind. This supports those endpoint results which might return multiple kinds.

Here is the request for the next one hundred items from the same results set:

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://appliance/api/v1.12/data/search?results_id=SG9zdABuco8EWAIAB9oAAAV84w%3D%3D&query=SEARCH+Host&offset=100'

HTTP/1.1 200 OK
[
  {
    "count": 2446,
    "headings": [...],
    "kind": "Host",
    "next": "https://appliance/api/v1.0/data/search?results_id=SG9zdABuco8EWAIAB9oAAAV84w%3D%3D&query=SEARCH+Host&offset=200",
    "next_offset": 200,
    "offset": 100,
    "results": [ <next 100 results> ],
    "results_id": "SG9zdABuco8EWAIAB9oAAAV84w=="
  }
]

See the /data/search endpoint for full details of navigating paginated results.

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 holding details of the error, with the following fields:

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

Boolean indicating whether the error is likely to happen again if the same request is re-submitted.

If true, then re-submitting the request after a short delay may result in success (for example if a back-end service was down but becomes available again).

If false then re-submitting the same request is unlikely to result in success (because the problem is likely to be in the request contents itself).

Here is an example request, resulting in the response 400 Bad Request:

curl -i -X GET -H 'Authorization: bearer <your_token>' 'https://appliance/api/v1.12/data/search?query=SEARCH%20Host&offset=-1'

HTTP/1.1 400 Bad Request
{
  "code": 400,
  "message": "'offset' cannot be negative",
  "transient": false
}

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid leaking information to the caller.

Was this page helpful? Yes No Submitting... Thank you

Comments