Getting Started with the CPaaS Management APIs

Overview

CPaaS’s Management APIs provide all the tools you need to monitor and manage your accounts, applications, phone numbers, notifications and usage statistics.

The Management APIs are implemented on the top of the HTTP protocol and can be used with a programming language of choice.

Management APIs Capabilities

CPaaS Management APIs support the following capabilities:

HTTPS and basic authentication
HTTP GET, POST, PUT and DELETE requests
XML or JSON responses

API Endpoint

The base for all the API URLs is: https://$DOMAIN/restcomm/2012-04-24

Supported HTTP Methods

GET: Lists or reads objects and includes the information needed to perform any Read operations on the object. Sample use: list all of the applications under your CPaaS account.

POST/PUT: Creates or updates objects. Most requests using the POST/PUT method require JSON/XML in the request body. Sample use: modify a Client under your CPaaS account.

DELETE: Removes objects. Sample use: delete an application or client under your CPaaS account.

Authentication

CPaaS Management APIs use basic HTTP authentication to restrict access to API endpoints to authenticated users only. After you sign up with CPaaS, you can find your Account SID and Auth Token by navigating to Your Profile → Account in the CPaaS Console.

Account SID and Token

You then need to use these credentials in your request’s Authorization header using Basic authentication type (i.e. Authorization: Basic <base64-encoded AccountSID:AuthToken>). Here’s how you would use an HTTP client to authenticate with CPaaS:

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID.json?PageSize=1  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '.json?PageSize=1',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '.json?PageSize=1',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + ".json?PageSize=1");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Requests

API resources are accessed via HTTPS requests utilizing UTF-8 format. Data passed to the API through POST and PUT requests should use urlencoded format (i.e. Content-Type: application/x-www-form-urlencoded).

Responses

CPaaS can return its API responses either in .json or .xml format depending on the suffix of the URL the request was made on. For example, a request sent to https://$DOMAIN/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json will yield a .json response, while a request sent to https://$DOMAIN/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.xml will yield an .xml response.

Paging

Some Management APIs support pagination by accepting as query parameters the page number we interested in as well as the page size. The following query parameters are supported:

Query Parameter	Description
Page	Which page of SMS records to return, starting from 0.
PageSize	Number of records returned per page.

Query Parameter

Description

Page

Which page of SMS records to return, starting from 0.

PageSize

Number of records returned per page.

For example, the following request will return the first page of results with a size of 10 items:

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json?Page=0&PageSize=10  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/SMS/Messages.json?Page=0&PageSize=10',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/SMS/Messages.json?Page=0&PageSize=10',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/SMS/Messages.json?Page=0&PageSize=10");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Getting started with the CPaaS Management APIs

Check out the following quickstarts to help you get started with the various Management APIs: