Get a sneak peek at APIs

Vivaldi Valentina
Apr 19, 2020 · 7 min read
Photo by Shahadat Rahman on Unsplash

The need of using an API comes mostly at the beginning of any data scientist career, while the necessity of creating one from scratch can happen a little bit later: luckily Python helps us in handling both situations in a pretty easy way.

The formal API (Application Programming Interface) definition is a set of subroutine definitions, protocols, and tools for building software and applications. It refers to a computing interface, a part of a computer program designed to be used or manipulated by another program, as opposed to an interface designed to be used or manipulated by a human. Computer programs frequently need to communicate amongst themselves or with the underlying operating system, both retrieving or sending data, and APIs are one way they do it.

Formal definition can seem very complicated, but there is a popular analogy that can help in understanding this concept. When you go to a restaurant as a customer, you need to know what is available for lunch, but of course you are not allowed to enter the kitchen. For this reason you have to check the menu and after having looked at it, you can make an order to a waiter, who passes it to the kitchen and who will then deliver what you have asked for. In order to choose what to eat, you look at the menu which provides a list of dishes you can order, along with a description of each one, but It does not contain the explanation of how exactly the chef prepares that food; that’s because you do not really need to know it.

The menu is the API documentation which explains what you can ask the API and the waiter is the API. You are the requester, someone who is asking for service, and the kitchen can be a system, a service, a website or a database that holds only certain type of data or functionality: in the kitchen there are only some ingredients and the chef has to decide what to offer accordingly with his capabilities. The order you placed is the request and the food delivered to you is the response.

All of us, both as professionals or just web user, mostly daily take advantage of APIs, although we may not notice. I’ll list in the following some simple everyday APIs example:

  • Weather data rich snippet. Every time “weather + [city’s name]” is typed on Google, a dedicated box with the current weather conditions and forecast is shown. However, Google is not the owner of weather data and the information are retrieved from a third party by means of an API.
  • Log-in using Facebook/Twitter/Google functionality which is on so many websites and save us a lot of time. All applications with this functionality leverage on these platforms’ API to authenticate the user. In more details when the user decides to log-in with a social media profile, the API provides the application with identification information, so it knows who’s logging in.
  • Travel booking websites. These kinds of websites are able to aggregate thousands of flights and/or destinations and showcase the cheapest option usually using third-party APIs to collect flight and hotel availabilities from providers. Likewise, once a booking has been made through one of this service, an API confirms immediately the availability of the trip.
  • Online payment. Everytime that an online payment (like VISA, MasterCard, PayPal) has been selected the application sends an “order” request to the Card API, specifying the amount owed and other important details. Then, a pop-up authenticates the user and confirms their purchase. If everything goes to plan, the API sends confirmation of payment back to the application.

It goes without saying, that there are many advantages in creating and using APIs, such as control access to hardware and software resources or allowing communication between services, but I would group them in two main categories:

  1. Retrieving Data
  2. Using already developed functionality

Retrieving Data

It’s way more convenient retrieving data using an API than exchanging them via for example a csv file, especially in situations like the following:

  • The data are changing quickly. Examples of this can be stock price or travel data. It doesn’t really make sense to regenerate a dataset and download it every minutes, this will take a lot of bandwidth and it will be pretty slow.
  • The real-time data are needed. For example in order to display them on a website or as part of an application, the data updated at that specific time can be required.
  • A small piece of a much larger set of data is needed. If you are interested in only one flight departure, it does not make sense to download all flight information. You can just filter data you need and retrieve only them.

Using already developed funcionality

Developer can definitely manage work faster and being productive in shorter time using the capabilities of one of the APIs than trying to independently implement similar functionality. Instead of writing the same code again they can directly focusing only on the new implementation part.

Moreover, the applications can be recharged with the latest technology. For example if you have do create a music classifier, Spotify has an API that can tell you the genre of a piece of music. Of course you can develop your own tool but it’s unlikely you will be able to have the same amount of data. This definitely helps reducing the amount of code developers need to create.

Usually when we refer to API, we allude to Web API which as the name suggests, is an API over the web that can be accessed using HTTP protocol. The most important concepts related with Web API are:

  • HTTP (Hypertext Transfer Protocol) is the primary means of communicating data on the web. HTTP implements a number of “methods,” which tell which direction data is moving, and what should happen to them.
  • URL (Uniform Resource Locator) is an address for a resource on the web, such as https://url_domain.org/about. A URL consists of a protocol (https://), domain (url_domain.org), and optional path (/about). A URL describes the location of a specific resource, such as a web page.
  • JSON (JavaScript Object Notation) is the most common format for exchanging data through an API; it’s text-based data storage format that is designed to be easy to read for both humans and machines.

In the following I will show you how API requests can be easily made or how an API can be straightforwardly created with Python.

How to make API Requests in Python?

First of all, in order to make an API request, the request library has to be installed as in the following:

pip install request

There are many different types of requests, the most commonly used is the GET one which is utilized to retrieve data (here you can find all the available methods).

Whenever a request is made, the response from the API comes with a response code which tells whether the request was successful and a response data.

The following command describes how to make a request and get respectively the response code and the data. (For the below example I am using an open API: http://open-notify.org/Open-Notify-API/)

response = requests.get(''http://api.open-notify.org/iss-now.json')
print(response.status_code)
print(print(response.json())

Sometimes, it can be also necessary to add some parameters to the request; a dictionary with the needed parameters can be defined, and then it can be passed into the requests.get function, as below:

parameters = {
"lat": 40.71,
"lon": -74
}
response = requests.get("http://api.open-notify.org/iss-pass.json", params=parameters)

However, everytime we need to make an API request, the API documentation gives us all the needed information such as the parameters required, the ones optional and the response format.

How to build an API in Python?

An API can be created using Python and the Flask web framework. After having installed flask, the following code creates a working web application and it allows us to implement an API.

import flask

The simpler example is the one which returns a database. For example we can add some data as a list of Python dictionaries, replacing the previous code as following:

import flask
from flask import request, jsonify

Once the code has been run and the server is running, visiting the URL you will be able to view the data in the catalog. You should see JSON output for the three entries in our test catalog. Flask provides us with a jsonify function that allows us to convert lists and dictionaries to JSON format. At this point, the very first and easy API has been created.

Another easy, but more interesting example, about building a weather app can be found here.

I have always thought about APIs as something that only software engineers can design or build , but I could not be more wrong. They are a very powerful tool for every developer or data scientists, that helps in gather useful data and to develop complex algorithms.

To deepen on this topic I suggest you the following very interesting and helpful links:

The Startup

Get smarter at building your thing. Join The Startup’s +800K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store