How to use REST API?
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 undersrand REST API format.
If we use our simplified hyphotetical weather example it 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. Sometimes you will also use the HTTPS protocol instead, where S stands for secure.
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 specifcally handles API requests.
Sometimes instead of having a subdomain, the software to hadndles 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 explantion 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 paremeters 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 seperate each parameter from the one the follows it.
- U=f - designates that the temperature units are requested in Fahrenheit.
- ? - a question mark designates where the request ends and the paremeters begin. In other words anything after the question mark are parameters.
The server will send you back this value in the form of JSON format that 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 friednly formatting to it, such as http://json.parser.online.fr/
Let's look at a real life API example -
With the following API you can contact Google Maps and recieve a lot of gerographical information about a location, including country, county, and longitude and latitude corrdinates.
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.
And an Actual Telebroad API exapmple -
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 authontication. 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 intially needed with this request (parameters are available to perform more fine tuned requests. See the myProfile specific instructions.)
See explnation of API authentication below.
The API method determines the nature of the operation perfomed 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 elbaorte manner, using an HTML header infomation. This is relevant to the Telebroad example.
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, authontication is more straightforward, and the JSON responses are easier to read with autmoatic formatting options.
One good free API client is caled Postman . It can be downloaded and installed for from the Chrome web store:
The app functions completely seperatly from the Chrome browser as a stand alone program.
As we seen above some REST API requests require an authoentication of a user ID and password on the website, usually to connetct to a specific account. This is sometimes reffered 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 authontication 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 transmittion (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--> email@example.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
Authorization: Basic dXNlckB0ZWxlYnJvYWQuY29tOmlsb3ZlcGJ4
To make things easy, just use Postman Inspector or other API client, where you can entrer 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.