General principles for using the REST API

This topic describes the principles common to the endpoints provided by the BMC Discovery REST API.

HTTP verbs

Where possible, endpoints use the following verbs consistently:

Verb	Purpose
GET	Retrieve a single resource, or collection of resources.
POST	Create 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.
PATCH	Update a resource, specifying the required target state of some fields. Any fields omitted are not modified. To delete a field, set it to null .
DELETE	Delete 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.0/data/search?query=search%20Host
https://appliance/api/v1.0/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.

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.0/discovery/runs

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

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.0/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.0/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:

Field

Meaning

code

The HTTP status code.

message

A 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.0/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.