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.
Where possible, endpoints use the following verbs consistently:
|GET||Retrieves a single resource or collection of resources.|
|POST||Creates a new resource.|
|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.|
|DELETE||Deletes a resource.|
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.
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:
|code||The HTTP status code.|
|message||A 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.