General principles for using the REST API
The API follows the REST architectural style, and uses both HTTP verbs and status codes. JSON is used for request and response bodies. The endpoints provided by the API are specified by using the Swagger specification language. All endpoints use the OAuth 2.0 protocol for authentication.
The following principles are common to the endpoints provided by the BMC Helix Business Workflows REST API:
Endpoint 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. Fields that are omitted, if any, are either reset to default values or deleted, as appropriate for the endpoint. |
PATCH | Updates a resource, specifying the required target state of some fields. Omitted fields are not modified. To delete a field, set it to null. |
DELETE | Deletes 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 that you correctly encode the characters that are not permitted in a URL. For example:
<example URL>
JSON format
JSON is used for both request and response bodies. If you are editing JSON request bodies manually, you must use the escape sequence for any reserved characters in your strings to avoid breaking the manually entered code.
Timestamps
All timestamps in response bodies are returned in ISO 8601 format:
YYYY-MM-DDTHH:MM:SS+HH:MM
URLs in responses
Several POST endpoints create a new resource, which can later be retrieved by using the API. In these cases, the response to the POST request includes a uri field, containing the URL of the newly created resource.
For example:
<example code and response>