How to use REST API requests?

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:

 


Let's break this down:


  • http:// - tells your browser to send the request to the server using the Hyper Text Transfer Protocol. This is the standard protocol to communicate with websites and you have most likely used it extensively while web surfing. It is also possible to use the HTTPS protocol instead, where S stands for secure. See more details below.

  • API.weatherserver.com - this is the URL - Uniform Resource Locator, basically the address of the website. You have probably already used this before to access regular websites, but the API in the address directs the browser to a subdomain of the site that specifically handles API requests.

    Sometimes instead of having a subdomain, the software to handle API requests will exist in a directory of the main site. For API functionality purpose this is just the same. The format in this case will look like - weatherserver.com/API/

  • /get - this specify what kind of REST API method we want to use. The "get" method tells the browser we want read information from the site. See explanation of more API methods below.

    In this example the different methods are broken by directories. Another format may define the method as something like this: method=request.get

    And yet another format will not divide the methods at all, but treat them as a whole set of commands, with the method of the command automatically defined by its name and usage.

  • /forecast - this is the API request itself. Each web site has a whole library of requests. Some offers only a handful and some offer dozens of different types of request. In this case our request is very straightforward - the forecast. This will return temperature and other forecast elements supplied by the server.

  • ?w=2459115&u=f - these are the parameters that fine tune the API request with certain data you want to obtain. In this case we want a weather forecast for a specific city in the world delivered in Fahrenheit degrees.

    • ? - a question mark designates where the request ends and the parameters begin. In other words anything after the question mark are parameters.

    • W=2459115 - is the location information for New York City. It is in a WOEID format (Where On Earth Identifier).

    • & - use the ampersand symbol to separate each parameter from the one the follows it.

    • U=f - designates that the temperature units are requested in Fahrenheit.


The server will send you back a response in JSON format (JSON stands for JavaScript Object Notation.)


The response will look something like this:

    

    {

         "query": {

          "count": 1,

          "created": "2017-08-22T10:12:25Z",

          "results": {

                "channel": {

                "item": {

                 "condition": {

                  "code": "33",

                  "date": "Tue, 22 Aug 2017 02:00 AM PDT",

                  "temp": "69",

                  "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/


Real Life API Example 


With the following API you can contact Google Maps and receive a lot of geographical information about a location, including country, county, and longitude and latitude coordinates. 


https://maps.googleapis.com/maps/api/geocode/json?address=Brooklyn


You can see the that all you have to do with this request is supply the address parameter, following the question mark.

Also note that it is specified that the response is requested in json format, as there are several possible formats for API requests. The Json format just happens to be the easiest to read. 


Actual Telebroad API Example


https://webserv.telebroad.com/api/teleconsole/rest/myProfile


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.

 


API Methods


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.


Using a Secured Connection


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. HTTP- 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.


API Client Apps


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):

https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop


Windows, Linux, and Mac OS versions are now also available at https://www.postman.com/downloads/


Authentication


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:


https://www.example.com/getaccount/auth?identity=<username>&password=<password>


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:


https://www.base64encode.org/


An example of how this it works:


User name-->user@telebroad.com

Password-->ilovepbx


Before encoding combine them into one string--> user@telebroad.com: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:


    GET/api/teleconsole/rest/myProfile HTTP/1.1
   

    Host: webserv.telebroad.com


    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.


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.