General principles for using the REST API

The API endpoints are specified using the Swagger specification language. All endpoints use the OAuth 2.0 protocol for authentication. JSON is used for request and response bodies.

The following principles are common to the endpoints provided by the BMC Helix Telco Extensions 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), make sure to encode special characters (like spaces or slashes) to ensure the URL is valid and correctly interpreted by the server.

For example:

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.