REST API Overview
CPaaS REST APIs power the Restcomm Communications Platform as a Service (CPaaS) and represent wide range of operations that enable you to create programmable Voice and SMS applications.You can use the REST APIs to create enterprise application that focus on your users needs.The REST APIs are implemented on the HTTP protocol, so you can use them with your preferred programming language and tools.
REST API Capabilities
A REST API client should support the following:
-
HTTPS and basic authentication
-
HTTP GET, POST, PUT and DELETE requests
-
Ability to set and read request and response headers
-
XML or JSON responses
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 Restcomm 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 Restcomm account.
DELETE: Removes objects.Sample use: delete an application or client under your Restcomm account.
Authentication
Restcomm APIs use basic HTTP authentication to restrict access to API endpoints to authenticated users only.After you sign up with Restcomm, you can find your Account SID and Auth Token by navigating to your profile
→ Account
in the Restcomm Console.
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 Restcomm:
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID.json \
-u 'YourAccountSid:YourAuthToken'
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
Restcomm 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/api/2012-04-24/Accounts/ACCOUNT_SID/Calls.json
will yield a .json
response, while a request sent to \https://$DOMAIN/api/2012-04-24/Accounts/ACCOUNT_SID/Calls.xml
will yield an .xml
response.
Paging
Some Restcomm 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. |
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'
Limit for Restcomm Accounting APIs
Restcomm Accounting APIs impose a limitation in the number of the total results that can be fetched by querying the specific APIs, using the Limit parameter.
The maximum value of the Limit parameter will be set by the system but user queries can provide a Limit value lower than the system default, to improve query results and response times.
The Limit parameter is a filter that can be used to restrict the total number of results to be fetched and improve the response times, while on the contrary the PageSize parameter will limit the number of records to be fetched for each page.
The Limit parameter will be included in the API response.
The following query parameter is supported:
Query Parameter | Description |
---|---|
Limit |
The total number of items in the list. |
For example, the following request will result in a response of 500 items:
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json?Limit=500 \
-u 'YourAccountSid:YourAuthToken'
Distributed Request Processing
The CPaaS platform has a distributed microservice architecture, that enables linear scalability during traffic growth and handles a high volume of REST API requests, voice calls, and SMS messages. Each architecture component handles different types of requests.
When you modify the provisioning data via the Management REST APIs, up to few minutes are needed for the update to reflect the changes in all call processing units that handle calls and SMS. Provisioning data modifications are done using the HTTP POST, PUT and DELETE methods. The POST method updates records immediately with no delay during the operation.
Distributed request processing is available for the following Management APIs, as well as the CPaaS Console.