Byte Introduction

Get started with REST APIs

Skills:

REST API

Objective

Get started with REST APIs

Background

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.

Primary goals

  1. Understand what REST APIs are

  2. Understand how to make REST API calls

Objective

Get started with REST APIs

Background

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.

Primary goals

  1. Understand what REST APIs are

  2. Understand how to make REST API calls

Getting started with REST APIs

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


Note

The APIs shown in the video might require authentication when you try it out

Trying it out

Excited about trying this out on your own? Use https://www.metaweather.com/api/location/search/?query=san or find one you like from here


Which ones did you try out? (You can try out a Chrome extension like JSONView to format the JSON response in your browser window)


As we discussed earlier, REST API calls are made on top of the HTTP protocol. We can analyse the network packets during the API calls to confirm this using Wireshark.
Wireshark is a popular network analysis tool to capture network packets and display them at a granular level. Once these packets are broken down, you can use them for real-time or offline analysis.


The client sends a HTTP GET request (line 8) to the server. The server responds with a 200 status code and JSON data on line 10. (API request was made to http://jsonplaceholder.typicode.com/posts, see doc)

image alt text

Visualizing API request-response packets using Wireshark

Curious Cats

Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.

Use Chrome Developer Tools to understand HTTP structure

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.


  1. To open Chrome Developer Tools, press Ctrl + Shift + i / Cmd + Shift + i in the browser window and select the Network tab.

image alt text

  1. Try visiting a website (eg: https://www.flipkart.com/) to see the HTTP requests getting populated. You will see many HTTP requests being made.

image alt text

  1. 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). image alt text

  2. Click on the entry to open a side-bar with information regarding the request & response for it

image alt text

Components of a REST API Request

Use Chrome’s Developer Tools to monitor the API request made. Let’s look at the different components of the REST API request.

  1. Request URL: https://www.metaweather.com/api/location/search/?query=san

  2. Request Method: GET which denotes the type of HTTP request made. GET means data needs to be fetched.

  3. Request Headers: eg: accept, accept-encoding - used to send additional info like the type of encoding that the requesting application (browser) supports

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

image alt text

The Request URL is made up of the

  1. Scheme: https - denotes the request was made using the HTTPS protocol ie, secure version of the HTTP protocol

  2. Root-endpoint: www.metaweather.com - defines the API provider

  3. Path: /api/location/search/ - there will be one api path for each type of resource. Here, we are asking for the resource named location. image alt text

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

image alt text

  • 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?

Curious Cats

  • Let’s say we need to use another parameter, country along with the query parameter to filter the locations for a particular country. How would we redesign the request URL, https://www.metaweather.com/api/location/search/?query=san for this purpose? (Note: the Metaweather API doesn’t support country parameter)

Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.

REST API calls using Programs

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

image alt text

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

  • Use the above API endpoint to find the value <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

Curious Cats

Answers to these Curious Cats questions will be available in the Takeaways milestone at the end.

LinkedIn with REST API

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!".


I’ll lead by example :). Goto https://www.linkedin.com/feed/ and add your post message.

image alt text

image alt text

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. image alt text

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

image alt text


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!

image alt text

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. No fun, right?


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)

image alt text


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!

Summary

Newfound Superpowers

  • Know-how of REST APIs

Now you can

  • Make REST API calls

  • Explain how REST API calls differ from normal HTTP requests for web pages