General principles for using the BMC Helix Digital Workplace Catalog 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.
Required license
HTTP verbs
Where possible, endpoints use the following verbs consistently:
Verb | Purpose |
|---|---|
GET | Retrieves a single resource or collection of resources. |
POST | Creates 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. |
DELETE | Deletes 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, which contains 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:
Field | Meaning |
|---|---|
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.