This documentation supports the 18.02 version of BMC Digital Workplace. To view the latest version, select the version from the Product version menu.

General principles for using the BMC Digital Workplace 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.

HTTP verbs

Where possible, endpoints use the following verbs consistently:

VerbPurpose
GETRetrieves a single resource or collection of resources.
POSTCreates a new resource.

PUT

Updates 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.
DELETEDeletes a resource.

JSON format

JSON is used for both request and response bodies.

URLs in responses

Some POST endpoints create new resources, which can later be retrieved by using the API. In these cases, the response to the POST request contains a "uri" field, containing the URL of the newly created resource.

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.

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