Basic REST API Format
REST API requests are generally programmed into an application and then sent to a website or server. This is done to enhance your application with a certain service or functionality.
However you can also send simple REST API requests directly from your browser’s address bar, to perform some operations more efficiently than using a web interface. It's also a good way to just practice and understand REST API format.
If we use our simplified hypothetical weather example a request will look like something like this:
The response will look something like this:
"date": "Tue, 22 Aug 2017 02:00 AM PDT",
"text": "Mostly Clear"
We are not only given the temperature in Fahrenheit - 69 degrees, but also the cloud coverage, which in the example is said to be "mostly clear".
Note that the way the JSON code is displayed depends on your browser settings and the website itself. Sometimes the code will be displayed in one long line. In this case just copy and paste it into a web site that will apply more user friendly formatting to it, such as http://json.parser.online.fr/
This request will return a response with many 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.
This is of course private information. This makes this API request different than the ones above, since it requires authentication. The details provided will only be given with proper username password identification, otherwise an error message will be returned.
The username will identify the user and hence no parameters are initially needed with this request (parameters are available to perform more fine tuned requests. See the myProfile specific instructions.)
See explanation of API authentication below.
The API method determines the nature of the operation performed by the API request.
The main methods available are:
Get - this method is used for reading information of a server or a web site. We have already seen a few examples of this above.
Post - this method is used for creating information on a server or a web site. An example would be creating a new e on a Twitter account, or creating a new SMS message that will be sent to a customer using a Telebroad account.
Put - this method is used for updating information on a server or a web site. An example would be updating an already existing message on a Twitter account.
Delete - this method is used for deleting information on a server or a web site. An example would be deleting an already existing message on a Twitter account.
Some websites divides the methods into different directories as seen the weatherserver example above.
With others the name of the request is already associated with a method - as in the Google maps example.
Yet, with others, the type of the method along with more information (including authentications) is sent in a more elaborate manner, using an HTML header information. This is relevant to the Telebroad example.
REST API requests and responses are communicated between client and server using the HTTP Internet protocol - Hyper Text Transfer Protocol.
HTTP is not a secured protocol and data sent over it is vulnerable. HTTPS - Hypertext Transfer Protocol Secure has been invented to address this issue. It uses what is known as 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 into 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 REST API you either do the same (typing HTTPS) or select HTTPS from a drop down menu in your API client app of choice.
Generally speaking, selecting which protocol to work with depends on your data. If you are just requesting a weather forecast you don't need a secure connection but for a list of clients phone number you do.
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.
Instead of typing API requests from a browser you can use an API client app for the same purpose. With such an app you can perform more complex API operations, authentication is more straightforward, and the JSON responses are easier to read with automatic formatting options.
One good free API client (with paid premium versions) is called Postman.
It can be downloaded and installed for from the Chrome web store (
It functions completely separately from the Chrome browser as a stand alone program):
Windows, Linux, and Mac OS versions are now also available at https://www.postman.com/downloads/
As we seen above some REST API requests require an authentication of a user ID and password on the website, usually to connect to a specific account. This is sometimes referred to as a private method, as opposed to a public method that offer services available without requiring an account with the website.
Some sites allow for authentication to be included as a parameter, as seen in this example:
The problem with this is that it makes the password and user name visible, and despite the the security protocols that encrypt the transmition (using HTTPS), it is still better to encode it.
There are several encoding methods. One of the most commonly used ones, which is popular with email programs, is called base64. It converts your user name and password into into one ASCII text string.
You can easily encode and decode base64 on a web site like:
An example of how this it works:
Before encoding combine them into one string--> firstname.lastname@example.org:ilovepbx
The encoded result will be-->dXNlckB0ZWxlYnJvYWQuY29tOmlsb3ZlcGJ4
This will be sent to the server as the following HTTP header for the Get/Myprofile API request:
Authorization: Basic dXNlckB0ZWxlYnJvYWQuY29tOmlsb3ZlcGJ4
To make things easy, just use Postman Inspector or other API client, where you can enter your user name and password as usual. Postman will handle all the base64 encoding and generate the HTML header automatically when you send the request.