Python Fundamentals
By:
Craft Software
Lesson: Working with API
An API, or Application Programming Interface, is a server that you can use to
retrieve and send data to using code. APIs are most commonly used to retrieve data
from a source and display it to a software application and it’s users.
When we want to receive data from an API, we need to make a request. Requests
are used all over the web.
APIs work in the same way as a browser when you visit a webpage, a request for
information is sent to a server and the server responds. The only difference is the
type of data that the server responds with, for APIs the data is of the type JSON.
JSON stands for JavaScript Object Notation, which is the standard data notation for
APIs in most software languages.
Python API Requests and Response Codes
Any request made to a server of any kind always returns a response object, that
response consists of multiple parts. There are two parts of that response that are
important for using APIs, one is called the status code and the other is the response
body.
The status code is used to indicate the status of the request, such as if it’s succeeded
or failed. There is a very large number of response codes that are used to indicate
different statuses, let’s look at a few examples.
• 200 (OK): Error-free success with a response.
• 301 : URL redirect
• 400: Bad request
• 401 (UNAUTHORIZED): Access denied
• 403: Forbidden request
• 404: Not found
• 503: Server error
Each of the response codes starts with a number which is used to help categorize
the responses. Responses starting with two indicate success, three indicates a URL
redirect, and the numbers four and five mean there was an error encountered.
Code range Category
2xx Successful operation
3xx Redirection
4xx Client error
5xx Server error
Making API Requests in Python
To work with APIs in Python, we need tools that will make those requests. In
Python, the most common library for making requests and working with APIs is
the requests library. The requests library isn’t part of the standard Python library,
so you’ll need to install it to get started.
If you use pip to manage your Python packages, you can install requests using the
following command:
pip install requests //for linux
python -m pip install requests // for windows
If you don’t have pip installed in your machine(windows), follow the steps below:
How to Install PIP on Windows
Before proceeding to PIP installation on Windows, we need to make sure that
Python is already installed, and PIP is not installed.
Check If Python Is Available
To verify that Python is available on our local machine, we need to open the
command line (in Windows search, type cmd and press Enter to open Command
Prompt or right-click on the Start button and select Windows PowerShell), type
python, and press Enter.
If Python is properly installed, we will see a notification like the one below:
Python 3.10.2 (…)on win32 Type "help," "copyright," "credits," or "license"
for more information.
If Python is not installed, download the latest python version from python for
windows and install it.
Now open your command line and run the following scripts:
curl [Link] -o [Link]
python [Link]
Now check if pip and python are installed properly,
python –version
pip --version
Back to business, the requests module (you installed it above) allows you to send
HTTP requests using Python. The HTTP request returns a Response Object with
all the response data (content, encoding, status, etc).
It has the following methods:
Method Description
delete(url, args) Sends a DELETE request to the specified url
get(url, params, args) Sends a GET request to the specified url
head(url, args) Sends a HEAD request to the specified url
patch(url, data, args) Sends a PATCH request to the specified url
post(url, data, json, args) Sends a POST request to the specified url
put(url, data, args) Sends a PUT request to the specified url
request(method, url, args) Sends a request of the specified method to the specified url
Making Our First API Request: GET method
There are many different types of requests. The most used one, a GET request, is
used to retrieve data.
When we make a request, the response from the API comes with a response code
which tells us whether our request was successful. Response codes are important
because they immediately tell us if something went wrong.
To make a ‘GET’ request, we’ll use the [Link]() function, which requires
one argument — the URL we want to make the request to. We’ll start by making a
request to an API endpoint that doesn’t exist, so we can see what that response
code looks like.
import requests
response = [Link]('[Link]
print(response.status_code)
The get() function returns a response object. We can use the response.status_code
attribute to receive the status code for our request:
All we need to do is enter the URL of the API we are sending a request to and
viola — we will receive a JSON response from the API!
Output: 404
The ‘404’ status code might be familiar to you — it’s the status code that a server
returns if it can’t find the file we requested. In this case, we asked for yourfile
which didn’t exist!
Working with JSON Data in Python
JSON (JavaScript Object Notation) is the language of APIs. JSON is a way to
encode data structures that ensures that they are easily readable by machines.
JSON is the primary format in which data is passed back and forth to APIs, and
most API servers will send their responses in JSON format.
When interacting with APIs we use a standardized template for sending and
receiving data so both the client (us) and the API can process the data correctly —
this format is the JavaScript Object Notation (JSON).
JSON implements the same hierarchical structure with key-value pairs that we see
in Python dictionaries. We can embed lists, strings, or even other dictionaries using
this structure.
JSON output we receive from the API looks like it contains Python dictionaries,
lists, strings, and integers. You can think of JSON as being a combination of these
objects represented as strings. Let’s look at a simple example:
To test out GET and the other methods in this section, you’ll use a service called
JSONPlaceholder. This free service provides fake API endpoints that send back
responses that requests can process.
API endpoints
A REST API exposes a set of public URLs that client applications use to access the
resources of a web service. These URLs, in the context of an API, are called
endpoints.
Example:
In the following url, [Link]
/todos is an endpoint
/todos/1 is another endpoint
Example:
Run the following commands to send a GET request to a JSONPlaceholder
endpoint:
import requests
api_url = '[Link]
response = [Link](api_url)
print(response.status_code)
print([Link]())
Let’s rewrite the above code in a method definition.
import requests
def jsonPrint(url):
response = [Link](url)
print([Link]())
// call the method
jsonPrint('[Link]
This code calls [Link]() to send a GET request to /todos/1, which responds
with the todo item with the ID 1. Then you can call .json() on the response object
to view the data that came back from the API.
The response data is formatted as JSON, a key-value store similar to a Python
dictionary. It’s a very popular data format and the de facto interchange format for
most REST APIs.
Beyond viewing the JSON data from the API, you can also view other things
about the response:
print(response.status_code)
Python has great JSON support with the json package. The json package is part of
the standard library, so we don’t have to install anything to use it.
We can both convert lists and dictionaries to JSON, and convert strings to lists and
dictionaries. The json library has two main functions:
• [Link]() — Takes in a Python object, and converts (dumps) it to a
string.
• [Link]() — Takes a JSON string, and converts (loads) it to a Python
object.
The dumps() function is particularly useful as we can use it to print a formatted
string which makes it easier to understand the JSON output, like in the diagram we
saw above:
import requests
api_url = '[Link]
response = [Link](api_url)
json_result = [Link]()
output = [Link](json_result, sort_keys = True, indent = 4)
print(output)
Challenge: How do you display a result as shown in the picture below:
Solution:
import requests
api_url = '[Link]
response = [Link](api_url)
json_result = [Link]()
for i in range(3):
output = [Link](json_result[i], sort_keys = True, indent = 4)
print(output)
Challenge: What if you only want the first 5 titles of the todos in the placeholder
Solution:
import requests
api_url = '[Link]
response = [Link](api_url)
json_result = [Link]()
for i in range(5):
print(json_result[i]['title'])
Now, what if you want to add your own data as a resource in the system? Use the
request method, POST() method.
Types of Requests
When we communicate with an API we will tend to make one of the following
requests:
• GET — Retrieve information from the API.
• POST — Create a new resource (e.g., add a new data record).
• PUT — Update an existing resource (e.g., change specific value in existing
record).
• DELETE — Delete an existing resource (e.g., delete a data record).
POST
import requests
api_url = '[Link]
my_todo = {"userId": 1, "title": "Swim at Lake Tana", "completed": False}
res = [Link](api_url, json = my_todo )
print(res.status_code)
print([Link]())
Patch
Next up, you’ll use [Link]() to modify the value of a specific field on an
existing todo. PATCH differs from PUT in that it doesn’t completely replace the
existing resource. It only modifies the values set in the JSON sent with the request.
You’ll use the same todo from the last example to try out [Link](). Here are
the current values:
import requests
api_url = '[Link]
my_todo = {"title": "Car wash"}
res = [Link](api_url, json = my_todo )
print(res.status_code)
print([Link]())
Delete
If you want to completely remove a resource, then you use DELETE. Here’s the
code to remove a todo:
import requests
api_url = '[Link]
res = [Link](api_url)
print(res.status_code)
print([Link]())
You call [Link]() with an API URL that contains the ID for the todo you
would like to remove. This sends a DELETE request to the REST API, which then
removes the matching resource. After deleting the resource, the API sends back an
empty JSON object indicating that the resource has been deleted.
How can we use real APIs like GitHub API
Let’s use the GitHub API to POST a new repo to our GitHub account.
Authorization — most APIs need us to include an authorization key with our
calls, if we miss this — we’ll usually return a 4xx code telling us we need
authorization.
Many APIs require you to register and obtain an API key in order to make API
calls
To get github APIs key, go to your github profile and generate Personal access
tokens.
Once you have the authorization key, we will use it to authenticate all of our
requests to the GitHub API like so:
import requests
from pprint import pprint
url = '[Link] // use your user name
user_data = [Link](url).json()
pprint(user_data)
Let’s create a repository in our GitHub account using Python.
import requests, json
payload = {
'name': "my_python_repo",
'public': "true"
token = 'ghp_H0ddt8v3khzer' //generate one for yourself
url = '[Link]
res = [Link](
url,
headers = {'Authorization': f'token {token}'},
data = [Link](payload))
print(res)
We can think of headers as the metadata we include alongside our request.
Using the data parameter of our request, we describe what we would like to do. In
here we include our payload which is a Python dictionary converted into a JSON
format string using [Link]
From that we will return the 201 Created response code — which tells us that the
request was successful and we have created a new resource.
To check, we can head over to Github.