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 following principles are common to the endpoints provided by the BMC Helix AIOps 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. |
JSON format
JSON is used for both request and response bodies.
API base URL
The API base URL consists of: <Scheme>://<Your BMC Helix Portal URL>/<EndpointPath>
The following example shows the URL components:
- Method: HTTPS method (also known as an operation or verb) that informs the web service about the type of operation you are requesting. The endpoints use the GET, POST, PATCH, PUT, and DELETE methods.
- Scheme: The protocol used by the API to transmit a request. All endpoints use the HTTPS protocol.
- BMC Helix Portal URL: The product base URL that you received in the activation email for your BMC Helix AIOps tenant.
- Endpoint path: Path specific to the particular endpoint you want to run. Based on the type of endpoint, this path might include path and query parameters that can help identify the resource selection criteria. The endpoint path will differ based on the API.
Supported HTTP status codes
When responding to requests, the REST API uses some of the standard HTTP status codes. The following table provides a summary of the status codes that are returned:
| Code | Value | Description |
|---|---|---|
200 | OK | The request was successful. The API returns the requested resource or confirms the update. |
201 | Created | A new resource, such as a service or configuration was successfully created. |
202 | Accepted | The request was accepted for processing, but the processing is not yet complete. |
204 | No content | The request was successful, but there is no response body. For example, after a successful DELETE. |
400 | Bad request | The request was invalid, typically due to missing or incorrect parameters. |
401 | Unauthorized | Authentication failed or missing. The client must provide a valid access token. |
403 | Forbidden | The client is authenticated but not authorized to perform the operation. |
404 | Not found | The requested resource does not exist. |
409 | Conflict | The request could not be completed due to a conflict with the current state of the resource. |
422 | Unprocessable entity | The request was well-formed but contained invalid data (for example, schema validation failed). |
500 | Internal server error | The server encountered an unexpected condition that prevented it from fulfilling the request. |
503 | Service unavailable | The server is currently unable to handle the request (temporary overload or maintenance). |