Jump to:
--
API (Application Programming Interface) requests are a communication mechanism between software components. REST API ia is a kind of API that is specifically designed as a web service. REST APIs can be embedded into a program and, when triggered, are sent to the relevant server to obtain information or use a certain service or functionality. For example, you can add VoIP calling functionality to an existing CRM application using Telebroad's APIs.
You can also just use API requests independently to perform some operations with more details or efficiently. For example, you can use an API to obtain all the text messages from a user's TeleConsole account as single text file. Doing so from the TeleConsole app itself will be much more laborious and time consuming.
A dedicated REST API client (such as Postman) provides a convenient environment for building and testing requests. You can also send simple REST API requests directly from the address bar of a web browser.
REST API Format
Every web service that supports REST APIs has its own unique vocabulary of requests, but the basic format is always the same. It starts with the web address of the service followed by a specific directory that handles API requests. Then the request is given followed by optional parameters. The first parameter is separated from the request by a question mark. Additional parameters are separated from each other by the ampersand symbol.
Example:
webserv.telebroad.com/api/teleconsole/rest/myProfile?&sms=1&fax=1&phones=1
This request will return details about a user's PBX account - his phone number, extension, his caller ID, address, Fax line, voicemail number, SMS line, language, time zone, and more. The three given parameters specify that extended information is requested for SMS, fax, and phones lines.
The requested details will only be provided with a proper user name and password for the relevant TeleConsole account, otherwise an error message will be returned. If you use a REST API client you define the authentication details before sending the request. If you just use a web browser you need to add a user name and password to the request.
See explanation of API authentication below.
API Methods
The API method determines the nature of the operation performed by the API request:
Get - used for reading information of a server or a web site.
Post - used for creating ne information on a server or a web site. An example would be creating a new SMS message that will be sent to a customer from a Telebroad account.
Put - used for updating information on a server or a web site. An example would be updating a TeleConsole contact's details.
Delete - this method is used for deleting information on a server or a web site. An example would be deleting a TeleConsole contact.
Using a Secured Connection
REST API requests and responses are communicated between client and server using standard HTTP protocol.
HTTP is not a secured protocol and data sent over it is vulnerable. HTTPS address this issue by using an SSL certificate (Secure Sockets Layer nowadays replaced by Transport Layer Security, but the name stuck) to encrypt the transported data.
With a website that has an SSL certificate you simply type HTTPS in the address bar followed by the rest of the URL to work over a secured connection. Most supported websites will switch you over automatically to HTTPS even if you just type HTTP.
With a REST API client you either do the same (typing HTTPS) or select HTTPS from a relevant drop down menu.
With Telebroad's APIs, it is recommended you always use HTTPS, if only to further protect your TeleConsole's authentication credentials. Most Telebroad APIs will actually not work if sent over HTTP, returning a "301" error.
Basic Authentication and Encoding
All of Telebroad's REST API requests require a user name and password credentials for authentication of a specific TeleConsole account. The credentials can be included in a request by using the Username and Password parameters.
The problem with this is that it makes the password and user name visible, and despite the the HTTPS security protocol that encrypt the transmition, it is still better to encode it for more security using the base64 method.
You can encode your credentials manually, but to make things easy just use an API client and enter your user name and password in the relevant Basic Authentication fields. The client will handle all the base64 encoding automatically when you send the request.
With some clients you can find an Authentication tab where you can select Basic Authentication.
With other clients you need to add a Basic Authentication header.
