Python Tutorial - Unit 24 | Working with APIs

Objective

In this unit, you will learn how to interact with web services using APIs (Application Programming Interfaces). By the end of this unit, you will understand how to make API requests in Python, parse JSON responses, and incorporate data from APIs into your turtle drawing program.

What is an API?

APIs are a set of rules and protocols that allow different software applications to communicate with each other. They define the methods and data formats that applications can use to request and exchange information. You can think of an API as a menu in a restaurant; the menu provides a list of dishes you can order, along with a description of each dish. When you specify what you want to order, the kitchen (i.e., the system's back end) prepares the dish and serves it to you.

For example, a weather API might allow you to retrieve the current weather for a specific location. You send a request to the API's URL (also called an endpoint), and the API returns the weather data in a specific format, usually JSON.

Making API Requests

In order to explore working with APIs, we need a remote service that can send us data. For our testing, we'll be using a free online service called dummyJSON. It provides placeholder data in JSON format, including posts, comments, users, and more. It's a great resource for testing and learning how to work with APIs in Python. You can find more information and examples in the dummyJSON documentation

To make API requests in Python, you can use the requests library. Here's an example that fetches a list of example blog posts from the dummyJSON API:

import requests

url = "https://dummyjson.com/posts"
response = requests.get(url)

if response.status_code == 200:
    print("Request was successful!")
    data = response.json()
    for post in data['posts'][:5]:  # Print the first 5 posts
        print(f"Title: {post['title']}")
else:
    print("Request failed!")

In this example, we're sending a GET request to the specified URL to fetch a list of blog posts. The response is stored in the response variable, which allows to check the status code to see if the request was successful. If the request is successful, we use the json() method to parse the JSON data and print the titles of the first five posts.

Working with the Requests Library

The requests library is one of the most popular libraries in Python for making HTTP requests to web services. It abstracts the complexities of making requests behind simple methods, allowing you to send HTTP/1.1 requests with various methods like GET, POST, PUT, DELETE, and others.

Installation

Before you can use the requests library, you need to install it. You can install it using pip:

pip install requests

Making GET Requests

You can use the get method to fetch data from the remote service (make a GET HTTP request):

import requests

response = requests.get('https://dummyjson.com/posts/1')
print(response.text)  # Prints the response body

Making POST Requests

You can use the post method to send data to the remote service (make POST HTTP request):

import requests

data = {'title': 'foo', 'body': 'bar', 'userId': 1}
response = requests.post('https://dummyjson.com/posts/add', json=data)

print(response.text)  # Prints the response body

Other HTTP Methods

The requests library also provides methods for other HTTP verbs:

requests.put(url, data): Sends a PUT request
requests.delete(url): Sends a DELETE request
requests.head(url): Sends a HEAD request
requests.options(url): Sends an OPTIONS request

Handling Response Status Codes

You can check the response status code to see if the request was successful:

if response.status_code == 200:
    print('Success!')
elif response.status_code == 404:
    print('Not Found.')
else:
    print('An error has occurred.')

You can also use the response.raise_for_status() method, which will raise an HTTPError if the HTTP request returned an unsuccessful status code:

try:
    response.raise_for_status()
    # Code here will only be executed if the request was successful
except requests.exceptions.HTTPError as err:
    raise SystemExit(err)

Handling JSON Responses

If the response content is in JSON format, you can use the json method to parse it into a Python object:

data = response.json()
print(data['title'])  # Prints the title of the post

Custom Headers

You can send custom headers with your request by using the headers parameter:

headers = {'User-Agent': 'my-app'}
response = requests.get(url, headers=headers)

Timeouts

You can set timeouts to your request to prevent it from hanging indefinitely:

response = requests.get(url, timeout=5)  # Timeout after 5 seconds

Sessions

If you want to persist certain parameters (like headers or authentication) across multiple requests, you can use a session:

with requests.Session() as session:
    session.headers.update({'User-Agent': 'my-app'})
    response = session.get(url)

The requests library provides a rich and elegant way to handle HTTP requests and responses, making it an essential tool for interacting with web services in Python. By understanding its core features and functionalities, you can efficiently work with remote APIs and web data in your projects.

JSON Data Format

As we've already seen in previous sections, APIs often work with data in JSON format. JSON (JavaScript Object Notation) is a common data format used for representing structured data. It is a human-readable, text-based format that can be used by any programming language, including Python. (It was initially derived from JavaScript, but has since become an open standard.) A JSON object is written in key/value pairs and can be nested.

Here's an example JSON object representing a person:

{
    "name": "John",
    "age": 30,
    "city": "New York"
}

NOTE: JSON is a text-based representation of structured data. This means, that while we speak of a JSON "object", the content is stored as a string. When we receive this data, it is up to us to convert this string into an object (dictionary) that we can use in Python. Similarly, if we need to create a JSON object, we must convert our data (stored in a Python dictionary) to a properly formatted JSON string.

Working with JSON

In Python, we use the standard json library to work with JSON data.

json.dumps

The json.dumps method converts a Python object into a JSON string.

import json

person = {
    "name": "John",
    "age": 30,
    "city": "New York"
}

person_json = json.dumps(person)
print(person_json)

# Output will be a string with JSON data
# {"name": "John", "age": 30, "city": "New York"}

You can also define the separators and indentation for pretty printing:

person_json = json.dumps(person, indent=4, separators=(",", ": "))
print(person_json)

# Output will be a string with JSON data formatted with spaces and
# line breaks to make it more readable.
# {
#     "name": "John",
#     "age": 30,
#     "city": "New York"
# }

json.loads

The json.loads method parses a JSON string and returns a Python object.

person_json = '{"name": "John", "age": 30, "city": "New York"}'

# Parse the JSON string into a Python Dictionary
person = json.loads(person_json)

print(person["name"])  # Output will be 'John'

json.dump

The json.dump method is used to write JSON data to a file-like object. Here's how you can use it to write a Python object to a file:

with open('person.json', 'w') as file:
    json.dump(person, file)

json.load

The json.load method is used to read JSON data from a file-like object. Here's how you can use it to read a JSON file:

with open('person.json', 'r') as file:
    person = json.load(file)
    print(person["name"])  # Output will be 'John'

Parsing an API JSON Response

When making an API request, the response might be in JSON format. You can parse that JSON data using Python's requests library:

import requests

url = "https://dummyjson.com/posts"
response = requests.get(url)

if response.status_code == 200:
    print("Request was successful!")
    data = response.json()

    # Prints the title of the first post
    print(f"Title: {data['posts'][0]['title']}")
else:
    print("Request failed!")

Sending JSON Data to an API

Sometimes you need to send data to the remote service. For example, let's assume we need to create a new blog post. We can do this by using the post() method of the request library and sending a JSON object in the request.

Here's an example:

import requests
import json

url = "https://dummyjson.com/posts/add"

payload = {
    "title": "Test blog post",
    "body": "This is a test blog post ...",
    "userId": 1
}

headers = {'Content-Type': 'application/json'}

response = requests.post(url, data=json.dumps(payload), headers=headers)

if response.status_code == 200:
    print("Post was created successfully!")
    print(response.json())
else:
    print("Request failed!")

Understanding how to work with JSON data in Python using the json module and related methods will enable you to handle structured data more effectively, whether you're building web applications, data processing tools, or other types of software.

Project: Fetch and Display a Random Quote Using Turtle

In this project, you'll use the requests library to fetch a random quote from the web and then use the Turtle graphics library to display the quote and its author on the screen.

Here's the code:

import turtle
import requests

# Make a GET request to the dummyJSON endpoint and parse out the quote and author
response = requests.get('https://dummyjson.com/quotes/random')
data = response.json()
quote = data['quote']
author = data['author']

# Create a new turtle screen and set its background color
screen = turtle.Screen()
screen.bgcolor("lightyellow")

# Initialize a turtle object
t = turtle.Turtle()
t.hideturtle()

# Position the turtle and display the quote
t.penup()
t.goto(0, 50)  # Position the quote
t.write(quote, align="center", font=("Arial", 16, "italic"))

# Position the turtle and display the author
t.goto(0, -50)  # Position the author
t.write(f"- {author}", align="center", font=("Arial", 14, "bold"))

# Wait until the window is closed
turtle.done()

When you run this code, it will fetch a random quote and its author from the web and then display them on a Turtle screen. The quote will be displayed in italic, and the author will be displayed in bold.

This project demonstrates how you can combine the requests library with Turtle graphics to fetch and display web content in a visually appealing way. Take some time to play with the code and try adding more features, such as buttons to fetch a new quote, or displaying additional information related to the quote.

In the next unit, you'll learn about debugging and error handling, essential skills for writing robust and error-free code.

If you enjoyed this article, please share.

Python Tutorial - Unit 23

Python Tutorial - Unit 25

Sharif Alexandre