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:

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.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, the duration of which depends on the version of BMC Discovery. Version 11.3 patch 3 and later have a timeout of ten minutes. Earlier versions have a timeout of four 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"
}

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

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.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.

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

Comments

  1. Martin Ronnelin

    How do I define the range to scan here if I have several different ip/ranges?

    "ranges": [
         "137.72.95.*"
       ],

    I have tried

    "ranges": [
         "137.72.95.1,137.72.95.1,137.72.95.1"
       ],

    But it doesn't seem to work.

    / Martin

    Jan 25, 2019 08:11
    1. Michele Marques

      Have you checked the information that we provide in Endpoints in the REST API? There is more information about specific endpoints.


      Jul 31, 2019 01:52
    1. Vinay Bellare

      Hi Martin,

      Apologies for the delay in our response. Have you managed to resolve your issue by referring to the suggested topic? Please let us know if you still need help.

      Nov 07, 2019 10:52
  2. Martin Ronnelin

    Hi Vinay. I got the answer in this post https://communities.bmc.com/thread/192341.

    Thank you.

    Nov 11, 2019 07:28
    1. Vinay Bellare

      Hi Martin,

      Thanks for replying. We're glad that you could resolve your issue using the Communities page. 

      Regards.

      Nov 11, 2019 09:51