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 Portal 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 is used for both request and response bodies.

The API base URL consists of: <Scheme>://<Your BMC Helix Portal URL>/<BasePath>/<EndpointPath>

The following example shows the URL components:

Method: Required HTTPS method (also known as operation or verb) that tells the web service about the type of operation you are requesting. The supported endpoints use GET, POST, PATCH, PUT, and DELETE methods.
Scheme: Protocol used by the API to transmit a request. HTTPS is the supported protocol for all the endpoints.
BMC Helix Portal URL: Product URL that you received in the activation email.
Service path: URL prefix used by all the API paths. Starts with a leading slash (/). The base path helps the web service identify the correct resource for running the API. This path also includes the API version.
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.