APIs
Introduction
An API (Application Programming Interface) is a set of rules and specifications that provide
a layer of abstraction between the client and server sides of software. Essentially, it allows
developers to request information or functionality without having to worry about the implementation (a.k.a abstraction). This is reminiscent of using modules to help ease the work
of the developer. On the other hand, it allows developers to give information or functionality without having to show their implementation. By the end of the handout, you will hopefully be able to read/understand an APIʼs documentation and then actually use an API in your
code.
The requests module
We will need some way to communicate with an API. The ‘requestsʼ module allows us to
reach an APIʼs endpoint (weʼll talk about what this is later). As with all modules, we need to
import it:
>>> import requests
>>>
If no errors are thrown, you are good to go :)
*However, you may not have the requests module installed on your machine:
ModuleNotFoundError: No module named 'requests'
For macOS
Open Terminal and type
pip install requests
If you have multiple versions of Python, make sure to specify which one. For example:
pip3.8 install requests
For Windows
Open the Command Prompt and type:
pip install requests
You might get something along the lines of:
'pip' is not recognized as internal or external command
Try
python -m pip install requests
To have ‘pipʼ on your machine so you can use it later to install other Python packages and to
have Python as an environment variable, go to your Python installer and select modify. You
can find the installer by typing in “Add or remove programs” in the start search bar. Make
sure to check off ‘pipʼ and ‘Add Python to environment variablesʼ, install, and then ‘pip install
requestsʼ again
API Registration and Documentation
So we know what an API is, but how can we use any arbitrary one? This depends on the API
itself, but the good ones have comprehensive documentation to help us navigate to the endpoints we want. An endpoint is a point of communication that we will make requests to. Depending on which endpoint we target and the type of request we make, we will get a specific
response or post some change to the API. For the handout, we will be dealing with get
requests.
Letʼs say you wanted to find out information on various movies and tv shows and analyze it
with Python code. Wouldnʼt it be amazing if we can almost ‘askʼ a database about a movie,
and it responds will all this information? This is one of the major benefits of APIs.
The Movie DB API does just that:
. First make an account:
https://www.themoviedb.org/account/signup
. Login and acquire a v3 auth key (weʼll use this to make requests) under Settings -> API:
https://www.themoviedb.org/settings/api
. Fill out the form with this information:
Type of use: Education
Name: CS1301
URL: www.gatech.edu
Application Summary: Educational Purposes. Intro to APIs.
. Let's start:
https://developers.themoviedb.org/3/getting-started/introduction
How to read the documentation:
In the left hand column we can see various categories. Look at the ‘Get Detailsʼ endpoint under ‘Moviesʼ:
We can see that this endpoint gets us the primary information about a movie. How do we use
this endpoint? If you look towards the bottom, you can see a template request URL. An APIʼs
documentation should at a minimum provide this template so that we can fill in our specific
parameters.
https://api.themoviedb.org/3/movie/{movie_id}?api_key=<<api_key>>&language=en-US
We would replace {movie_id} with the id of the movie we are interested in, and replace
<<api_key>> with our api key (this will make sure that we are registered user of the api)
With other apis, you might need an api key in order to access the API endpoint's contents.
Be sure to read the documentation in order to understand how to format your API URL.
https://api.themoviedb.org/3/movie/155?api_key=sdhdhahdk163dsa1238&language=en-US
The Movie DB API is great and provides a ‘Try it outʼ section that will build the url request for
you if you provide the desired parameters. However, not all APIs will have this and you should
be able to parse through the template url and figure out what you need to supply. The parameters and variables are usually surrounded by {} and <<>>.
The documentation may also show what you will type of things you will get in the response:
This endpoint will respond with information about a movie. For example, the budget, the
genres, popularity, etc.
The response you get for one endpoint may contain arguments you may supply to another
endpoint. Since each genre has an id (as shown above), thereʼs most likely an endpoint for
getting information on a genre based on its id.
Remember to always explore the documentation, see what the template requests require,
and check if the response gives the information youʼre interested in.
Making Requests to APIs
Now, letʼs use the requests module, our api key, and templates to get actual information in
Python.
Here is the general recipe for making a request:
import requests
response = requests.get("YOUR_ENDPOINT_URL_GOES_HERE")
data = response.json()
We use the requests module to hit the specified api endpoint in our url.
requests.get() returns a request object
the .get() method takes in the URL as a string of the API that you are trying to receive
data from
some API URL endpoints require an api key in order to retrieve the data (the Movie DB
API requires a unique api key per user)
We call .json() to retrieve and decode the JSON object into a Python object (usually a
dictionary or list)
What is JSON?
JSON stands for JavaScript Object Notation. We need a way to have a standardized format
when sharing information across different platforms. There are hundreds of languages and
thousands of APIs out there. Imagine how hectic it would be if everyone sent and deciphered
information in their own special way? JSON standardizes the format of data returned from
and sent to an API so that computers can easily understand it.
What's next?
After calling .json() on the request object, we are left with any old dictionary or list problem.
It may be overwhelming because a response can contain a ton of information, but just take it
one step at a time and always check what is the data type you are working with. You can get
a dictionary who has a key that maps to a list of dictionaries and another key that maps to
another dictionary. It may be helpful to use the ‘pprintʼ module to easily visualize the data.
from pprint import pprint
pprint(data)
Here is part of the data retrieved for ‘The Dark Knightʼ:
{
"adult": false,
"backdrop_path": "/hqkIcbrOHL86UncnHIsHVcVmzue.jpg",
"belongs_to_collection": {
"id": 263,
"name": "The Dark Knight Collection",
"poster_path": "/bqS2lMgGkuodIXtDILFWTSWDDpa.jpg",
"backdrop_path": "/xfKot7lqaiW4XpL5TtDlVBA9ei9.jpg"
},
"budget": 185000000,
"genres": [
{
"id": 18,
"name": "Drama"
},
{
"id": 28,
"name": "Action"
},
{
"id": 80,
"name": "Crime"
},
{
"id": 53,
"name": "Thriller"
}
],
#a lot more stuff...
}
If we want to find all the ids of the genres of the movie so that we can then request information on:
for genre in data["genres"]: #data[“genres”] is a list
id = genre["id"] #genre is a dictionary
response = requests.get("ENDPOINT_URL_USING_GENRE_ID")
genre_data = response.json()
Key Points
APIs (Application Programming Interfaces) allow developers to request information or
functionality without having to worry about the implementation. On the other hand, it
allows developers to give information or functionality without showing their
implementation.
JSON (JavaScript Object Notation) standardizes the format of data returned from and
sent to an API so that computers can easily understand it.
The requests .get() method returns a response object.
Examples of APIs can be a weather api, movie api, sports api, or anything that deals with
information :)