Get started with REST APIs
Get started with REST APIs
Ever wondered how
Paytm or similar mobile apps make payments from Flipkart. Does Flipkart have Paytm’s code to do that?
Google Sign-in works on websites like medium.com. Does Google share their user data with Medium?
Web applications for facebook, twitter or gmail fetch data from their backend servers
APIs (Application Program Interface) are how different software programs communicate with each other. Application developers specify the rules of "How to communicate" with their application, these are APIs.
For example, Google Maps API specifies how other applications can use it to provide maps services to their users.
Usually, when we talk about API, we mean REST API. We’ll take a closer look at REST APIs in this Byte.
Understand what REST APIs are
Understand how to make REST API calls
Get started with REST APIs
Ever wondered how
Paytm or similar mobile apps make payments from Flipkart. Does Flipkart have Paytm’s code to do that?
Google Sign-in works on websites like medium.com. Does Google share their user data with Medium?
Web applications for facebook, twitter or gmail fetch data from their backend servers
APIs (Application Program Interface) are how different software programs communicate with each other. Application developers specify the rules of "How to communicate" with their application, these are APIs.
For example, Google Maps API specifies how other applications can use it to provide maps services to their users.
Usually, when we talk about API, we mean REST API. We’ll take a closer look at REST APIs in this Byte.
Understand what REST APIs are
Understand how to make REST API calls
REST stands for REpresentational State Transfer. Don’t worry - no one’s gonna ask you the meaning of each word :)
API stands for Application Programming Interface, and unfortunately, people will ask you the meaning of each word here. An API is like a waiter in a restaurant. You don’t go into a cafe and walk straight into the kitchen to tell the chef what you wanna eat. The waiter does that for you, and that’s exactly what an API is - with the client being you, the customer and any resource that can send data, being the chef.
Now, these APIs have different styles, or in more formal terms - conventions and architectures about how they are used.
REST APIs are those APIs which follow the guidelines set by the REST architecture. They follow a client-server model where one software program sends a request and the other responds with some data. REST APIs commonly use the HTTP protocol to send requests & receive responses.
How an API request differs from a usual HTTP request for a webpage, is in terms of the data returned. HTTP requests for webpages return HTML, CSS & JavaScript files which are rendered by the browser and displayed to the user. But, in the case of APIs, the request can be for any data (not just webpage) and the response is read by the requesting program which interprets the data.
JSON (JavaScript Object Notation - how cryptic :| ) is a standard format that is easily "understandable" by applications and can be handled well in most languages. So the data format in REST is usually JSON. For example, an Android app can effortlessly utilize data sent by a Node.js server. XML is another popular format for data transfer between applications.
The following video will give you a quick overview of REST API.
The APIs shown in the video might require authentication when you try it out (Authentication is done so that a spammy bot(aka, hacker) doesn’t send ten quadrillion requests to a resource and blast its servers out. It can be caught and stopped)
Are the API endpoints case sensitive i.e, if requests to /location & /Location must return the same response? Try it out for https://www.metaweather.com/api/location/search/?query=san
Why is it that you are able to make a REST API call via the browser?
Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.
If you already know how to use Chrome Developer Tools, you can skip this section and move on to the next section.
Chrome browser provides inbuilt tools to peek into the HTTP traffic it makes. This information can be used to better understand what’s happening behind the scenes when some URL is visited or an action like clicking the Login button is performed.
Ctrl + Shift + i
/ Cmd + Shift + i
in the browser window and select the Network
tab.Scroll to the top of the network activity to find a HTTP GET request to www.flipkart.com. (Find the entry In the Name
tab, you should see www.flipkart.com
with Type
as document).
Click on the entry to open a side-bar with information regarding the request & response for it
Use Chrome’s Developer Tools to monitor the API request made. Let’s look at the different components of the REST API request.
Request URL: https://www.metaweather.com/api/location/search/?query=san
Request Method: GET which denotes the type of HTTP request made. GET means data needs to be fetched.
Request Headers: eg: accept, accept-encoding - used to send additional info like the type of encoding that the requesting application (browser) supports
Request Body: is empty for the current request but can be used for sending additional information like a file’s content when uploading it to the server.
The Request URL is made up of the
Scheme: https - denotes the request was made using the HTTPS protocol ie, secure version of the HTTP protocol
Root-endpoint: www.metaweather.com - defines the API provider
Path: /api/location/search/ - there will be one api path for each type of resource. Here, we are asking for the resource named location.
Query parameter: ?query=san - the part of the URL that comes after a ? character is the query parameter. It specifies the search criteria for the resource. Here, the locations returned get filtered by the value of the query parameter, query we provide.
For every API request, the corresponding API response also contains HTTP headers that the server sends back along with the data requested. See if you can answer some questions based on these response headers.
What are the HTTP methods this API endpoint supports?
What is the data format sent by the server?
Check the response encoding used. Was it included among the accept-encoding request header sent to the server?
Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.
We saw how to make REST API calls using the browser. But, what was the purpose of having an API? It was for applications to communicate with each other, right? Let’s now see how to do that programmatically.
Use curl
on your command line to make a REST API call to https://www.metaweather.com/api/location/search/?query=san. This fetches location information for locations matching the query parameter san
Let’s see how to do the same using a Python program
# Import a library that allows to make HTTP request
import requests
# Set the API endpoint
url = "https://www.metaweather.com/api/location/search/?query=san"
# Use the library to perform an HTTP GET request to the URL
response = requests.get(url)
# Print out the data
print(response.text)
Try the program out and see if you get a similar response to that with curl
. You can use this online Python client to run the code.
Java program to do the same
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
public class Main {
public static void main(String[] args) throws MalformedURLException, IOException {
// create url
URL url = new URL("https://www.metaweather.com/api/location/search/?query=san");
// Send Get request and fetch data
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
BufferedReader br = new BufferedReader(new InputStreamReader(
(conn.getInputStream())));
// Read data line-by-line from buffer & print it out
String output;
while ((output = br.readLine()) != null) {
System.out.println(output);
}
conn.disconnect();
}
}
You can use this online Java client to try the code and play around making changes. Spring framework provides a RestTemplate class if you don’t want to deal with lower level details like opening a connection & buffers.
Do the below tasks
<woeid>
attribute for your city (if you get an empty response for your city, try bangalore :) )(A WOEID (Where On Earth IDentifier) is a unique 32-bit reference identifier that identifies any feature on Earth)
Use the woeid value you found to call this API endpoint - replace "(woeid)" with your city’s woeid value - https://www.metaweather.com/api/location/(woeid)/
In the response, the weather_state_name attribute denotes what the weather will be like Light Rain, Clear etc on a particular day denoted by the applicable_date parameter. Find the weather for today.
Challenge Task - Write a program to print out the weather for today using the above API endpoints
Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.
Congrats! REST APIs aren’t a mystery anymore. Why don’t you let the world know about it? Share a post on LinkedIn - "Got introduced to REST API!".
You can also find a video on the same here
I’ll lead by example :). Goto https://www.linkedin.com/feed/ and add your post message.
Wait! Now that we know most of the communication these days are via REST APIs, why don’t we keep the Chrome Developer Tools window open when we click the Post button?
An HTTP POST request to https://www.linkedin.com/voyager/api/contentcreation/normShares happened when the Post button was clicked. This could be the API endpoint that LinkedIn used to post our message.
Click on the request entry to open it & see if you can find the post message in the Request Payload section in the Headers tab
Yep, it’s there. Let’s try to use the curl
command to perform the same action. DevTools will give you that out of the box!
Before you get all excited and execute the curl
command copied from DevTools, take a step back and think what would happen if you do that - You’ll again post the same message. Or maybe not even that - you might get a 409 code ‘Resource already exists’ if you repeat the exact same request.
Copy-paste the curl
command to a text file, search for your post message (it’ll be part of the --data-binary flag), and change it to something else. Try executing the command from your terminal now, are you able to see this message posted?
(There’s a text parameter with value Got introduced to REST API for me. I updated it to Enjoying Learn By Doing with Crio.Do for the new post)
But, how did LinkedIn know whose account to post the message to?
If you observe carefully, you will see cookies from the browser get sent as a part of the request. This is what LinkedIn uses to identify your account. This cookie gets refreshed periodically, so it may not remain valid forever. A new one would be generated after a while.
We saw how to post messages using the REST API LinkedIn provided. Why don’t you try the same with Youtube? See if you can find out the API endpoint used to search for videos.
Pretty cool, right? Go wild, doing cool things with REST API!
We have learnt what REST API is by running some of the APIs.
APIs makes it easier for
Applications to expose their services
Other applications to avail those services.
Integration is easier, only the API definitions need to be exposed.
The internet is full of such APIs and the knowledge of APIs will help you utilize these services as well as to develop new ones of your own
Find pointers to the Curious Cats questions here
Further Reading
What’s REST and how it differs from GraphQL?
What’s an API, how do you ‘hit’ an API? How do you query APIs?
What are three things you’ll keep in mind when creating a REST API?
Make REST API calls
Explain how REST API calls differ from normal HTTP requests for web pages