1. REST API for <ProductName>REST API for Enterprise Communications Broker, Release 4.0.0
  2. Quick Start

Quick Start

Complete these tasks to set up your environment and then use the REST API to get the lock that is required before editing the configuration of the Enterprise Communications Broker (ECB).

Prerequisites

Prerequisite More Information
Install cURL Use cURL
Enable HTTPS Enable HTTPS
Authenticate Authenticate

Task 1: Obtain Account Information

From your account administrator, obtain the appropriate account credentials to enable you to log in to the ECB. Specifically, you will need:

  • User name and password

  • The IP address of the ECB.

Task 2: Get an Access Token

Request an access token by sending a POST request to /rest/{version}/auth/token. The ECB uses Basic Access Authentication to generate access tokens, so the client must send an Authentication header that contains the literal string Basic, a space, and the base64 encoding of the string admin:<password>.

For example: 

Authorization: Basic YWRtaW46Y29ycmVjdCBob3JzZSBiYXR0ZXJ5IHN0YXBsZQ==

To send the credentials with cURL: 

curl -X POST \
    --header "Accept: application/xml" \
    --user admin:<password> \
    'https://10.0.0.2/rest/v1.1/auth/token'

The <data> element of the response contains an <accessToken> element that contains the access token.

Export this value to a variable for easy use in subsequent calls. 

export TOKEN='YWRtaW4sYWRtaW4sMjAxOC0wOC0wOSAxOToyNzowzVmM2FhNGMzZjMyZDlkNWJmYzg4OGViMWU1ODQ4ZWIwZDMwZWM5NmI2NGE3ZWZjYzQxYjJiOWQ4MGRhN2Q1NWQ2NjIyNmUwNDExNTBmOWE2NGExY2E1ZTA4YmQ2OTFkOTY3ZjUxYmZkYjY5'

Send this token in subsequent requests within the Authorization header where the value is the literal string Bearer, a space, and the token. See Task 3 for an example.

Task 3: Get the Configuration Lock

All requests that change the system configuration are protected with a configuration lock. This prevents multiple users from making contradictory modifications simultaneously. If a REST client attempts a protected operation without first acquiring the configuration lock, the ECB returns the HTTP response code 423 Locked. The lock is acquired by sending a POST request to /rest/{version}/configuration/lock. 

curl -X POST \
    --header "Accept: application/xml" \
    --header "Authorization: Bearer $TOKEN" \
    'https://10.0.0.2/rest/v1.1/configuration/lock'

If the request is successful, you will receive a 204 No Content.

Task 4: Release the Configuration Lock

When a REST client finishes its configuration-affecting operations, it should release the lock by sending a POST request to /rest/{version}/configuration/unlock. This allows other users to acquire the configuration lock and modify the system. 

curl -X POST \
    --header "Accept: application/xml" \
    --header "Authorization: Bearer $TOKEN" \
    'https://10.0.0.2/rest/v1.1/configuration/unlock'