🌐 Lesson 10: Working with APIs

🔌 What Is an API?

An API (Application Programming Interface) is a set of rules that lets one piece of software talk to another. When you check the weather on your phone, the app doesn't generate forecasts itself — it sends a request to a weather service's API and displays the response.

Think of it like ordering at a restaurant:

• You (the client) look at the menu (the API documentation)
• You give your order (the request) to the waiter (the API)
• The kitchen (the server) prepares your food and the waiter brings it back (the response)

📡 REST & HTTP Basics

Most web APIs follow the REST (Representational State Transfer) pattern. REST APIs use standard HTTP methods to perform operations on resources — things like users, posts, products, or weather data — identified by URLs.

HTTP Methods

Each HTTP method signals a different intent:

HTTP Status Codes

Every response includes a status code — a three-digit number that tells you what happened:

URLs & Endpoints

A REST API organizes resources into predictable URLs called endpoints:

# Base URL
https://api.example.com/v1

# Endpoints (resources)
GET  /users          → List all users
GET  /users/42       → Get user with id 42
POST /users          → Create a new user
PUT  /users/42       → Replace user 42
DELETE /users/42     → Delete user 42

📦 The requests Library

Python's standard library includes urllib for making HTTP requests, but it's verbose and awkward. The third-party requests library is the de facto standard — simple, powerful, and beloved by the Python community.

Installation

Install it in your virtual environment (remember Lesson 9?):

# Create and activate a venv first!
python -m venv .venv
source .venv/bin/activate   # Linux/Mac
# .venv\Scripts\activate    # Windows

# Install requests
pip install requests

Your First Request

import requests

response = requests.get("https://httpbin.org/get")
print(response.status_code)   # 200
print(type(response))         # <class 'requests.models.Response'>

That's it — one line to make an HTTP GET request. The requests.get() function returns a Response object packed with useful attributes:

📥 Making GET Requests

GET is the most common HTTP method — it retrieves data without changing anything on the server. Let's use a free public API to fetch real data.

Example: Fetching a Random User

import requests

url = "https://randomuser.me/api/"
response = requests.get(url)

if response.ok:
    data = response.json()
    user = data["results"][0]
    name = f"{user['name']['first']} {user['name']['last']}"
    email = user["email"]
    country = user["location"]["country"]
    print(f"Name:    {name}")
    print(f"Email:   {email}")
    print(f"Country: {country}")
else:
    print(f"Request failed: {response.status_code}")

Name:    Sofia Andersen
Email:   sofia.andersen@example.com
Country: Denmark

Example: Fetching Multiple Items

import requests

# JSONPlaceholder — a free fake REST API for testing
url = "https://jsonplaceholder.typicode.com/posts"
response = requests.get(url)
posts = response.json()  # Returns a list of 100 posts

print(f"Total posts: {len(posts)}")
print(f"First post title: {posts[0]['title']}")

# Print the first 3 posts
for post in posts[:3]:
    print(f"\n[Post {post['id']}] {post['title']}")
    print(f"  {post['body'][:80]}...")

📋 Working with JSON

JSON (JavaScript Object Notation) is the standard data format for web APIs. It maps directly to Python data structures:

Parsing JSON from a Response

import requests

response = requests.get("https://jsonplaceholder.typicode.com/users/1")
user = response.json()   # Parses JSON string → Python dict

# Navigate the nested structure
print(user["name"])                    # "Leanne Graham"
print(user["address"]["city"])         # "Gwenborough"
print(user["company"]["catchPhrase"])  # "Multi-layered client-server neural-net"

The json Module

Python's built-in json module handles conversion between JSON strings and Python objects. You'll use it when saving API data to files:

import json

# Python dict → JSON string
data = {"name": "Ada", "languages": ["Python", "Haskell"]}
json_string = json.dumps(data, indent=2)
print(json_string)

# JSON string → Python dict
parsed = json.loads(json_string)
print(parsed["name"])  # "Ada"

# Save to file
with open("user_data.json", "w") as f:
    json.dump(data, f, indent=2)

# Load from file
with open("user_data.json") as f:
    loaded = json.load(f)
    print(loaded)  # {'name': 'Ada', 'languages': ['Python', 'Haskell']}

🔧 Query Parameters & Headers

Query Parameters

Many APIs accept query parameters — key-value pairs appended to the URL after a ?. Instead of building the URL string manually, pass a params dict:

import requests

# ❌ Manual URL building — error-prone, no encoding
url = "https://api.example.com/search?q=python+tutorial&limit=5"

# ✅ Use the params argument — clean and auto-encoded
url = "https://api.example.com/search"
params = {
    "q": "python tutorial",
    "limit": 5,
    "sort": "relevance"
}
response = requests.get(url, params=params)
print(response.url)
# https://api.example.com/search?q=python+tutorial&limit=5&sort=relevance

Real Example: Searching the Open Library API

import requests

url = "https://openlibrary.org/search.json"
params = {"q": "dune frank herbert", "limit": 3}
response = requests.get(url, params=params)
data = response.json()

print(f"Found {data['numFound']} results.\n")
for book in data["docs"][:3]:
    title = book.get("title", "Unknown")
    author = ", ".join(book.get("author_name", ["Unknown"]))
    year = book.get("first_publish_year", "N/A")
    print(f"📖 {title}")
    print(f"   by {author} ({year})\n")

Custom Headers

HTTP headers carry metadata about the request — content type, authentication, user-agent, etc. Pass them via the headers argument:

import requests

headers = {
    "Accept": "application/json",
    "User-Agent": "MyPythonApp/1.0"
}
response = requests.get(
    "https://httpbin.org/headers",
    headers=headers
)
print(response.json())

📤 POST Requests & Sending Data

While GET retrieves data, POST sends data to the server to create or process something. Use the json parameter to send JSON data automatically:

import requests

url = "https://jsonplaceholder.typicode.com/posts"
new_post = {
    "title": "Learning APIs with Python",
    "body": "The requests library makes it incredibly easy!",
    "userId": 1
}

response = requests.post(url, json=new_post)
print(response.status_code)  # 201 (Created)
print(response.json())
# {'title': 'Learning APIs with Python', 'body': '...', 'userId': 1, 'id': 101}

Other HTTP Methods

import requests

base = "https://jsonplaceholder.typicode.com/posts"

# PUT — Replace entire resource
response = requests.put(f"{base}/1", json={
    "id": 1,
    "title": "Updated Title",
    "body": "Completely replaced body.",
    "userId": 1
})
print(f"PUT: {response.status_code}")   # 200

# PATCH — Partial update
response = requests.patch(f"{base}/1", json={
    "title": "Only Changing the Title"
})
print(f"PATCH: {response.status_code}")  # 200

# DELETE — Remove resource
response = requests.delete(f"{base}/1")
print(f"DELETE: {response.status_code}") # 200

🔐 Authentication

Many APIs require you to prove who you are before they'll respond. The most common methods are API keys and Bearer tokens.

API Key in Query Parameters

Some APIs expect the key as a query parameter:

import requests

API_KEY = "your_api_key_here"  # Get from the service's dashboard

response = requests.get(
    "https://api.example.com/data",
    params={"api_key": API_KEY}
)

API Key in Headers

Others expect it in a custom header:

import requests

API_KEY = "your_api_key_here"

response = requests.get(
    "https://api.example.com/data",
    headers={"X-API-Key": API_KEY}
)

Bearer Token (OAuth2-style)

Many modern APIs use a Bearer token in the Authorization header:

import requests

TOKEN = "eyJhbGciOiJIUzI1NiIsInR5..."  # Obtained through login/OAuth flow

response = requests.get(
    "https://api.example.com/me",
    headers={"Authorization": f"Bearer {TOKEN}"}
)

import os
import requests

API_KEY = os.environ.get("MY_API_KEY")
if not API_KEY:
    raise RuntimeError("Set MY_API_KEY environment variable")

response = requests.get(
    "https://api.example.com/data",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

# Linux/Mac
export MY_API_KEY="abc123secret"

# Windows (PowerShell)
$env:MY_API_KEY = "abc123secret"

🛡️ Error Handling & Retries

Real-world APIs fail. Servers go down, networks drop, rate limits kick in. Robust code handles all of these gracefully.

Basic Error Handling

import requests

try:
    response = requests.get(
        "https://api.example.com/data",
        timeout=10  # seconds — always set a timeout!
    )
    response.raise_for_status()  # Raises HTTPError for 4xx/5xx
    data = response.json()

except requests.exceptions.Timeout:
    print("⏰ Request timed out — try again later")

except requests.exceptions.ConnectionError:
    print("🔌 Could not connect — check your network")

except requests.exceptions.HTTPError as e:
    print(f"🚫 HTTP error: {e.response.status_code}")
    if e.response.status_code == 404:
        print("   Resource not found")
    elif e.response.status_code == 429:
        print("   Rate limited — slow down!")

except requests.exceptions.RequestException as e:
    print(f"❌ Request failed: {e}")

Timeouts

Always set a timeout. Without one, your program could hang forever waiting for a server that never responds:

# timeout=10 → max 10 seconds total
response = requests.get(url, timeout=10)

# Separate connect and read timeouts
response = requests.get(url, timeout=(3.05, 27))
#                                     connect  read

Simple Retry Logic

import time
import requests

def fetch_with_retries(url, max_retries=3, backoff_factor=1):
    """Fetch a URL with exponential backoff on failure."""
    for attempt in range(max_retries):
        try:
            response = requests.get(url, timeout=10)
            response.raise_for_status()
            return response

        except (requests.exceptions.ConnectionError,
                requests.exceptions.Timeout) as e:
            wait = backoff_factor * (2 ** attempt)  # 1s, 2s, 4s
            print(f"Attempt {attempt + 1} failed: {e}")
            print(f"Retrying in {wait}s...")
            time.sleep(wait)

        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 429:
                wait = backoff_factor * (2 ** attempt)
                print(f"Rate limited. Retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise  # Don't retry other HTTP errors

    raise requests.exceptions.ConnectionError(
        f"Failed after {max_retries} retries"
    )

# Usage
response = fetch_with_retries("https://api.example.com/data")
data = response.json()

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retries = Retry(total=3, backoff_factor=1,
                status_forcelist=[429, 500, 502, 503, 504])
session.mount("https://", HTTPAdapter(max_retries=retries))

response = session.get("https://api.example.com/data", timeout=10)

🏗️ Mini-Project: Country Info Dashboard

Let's bring it all together. We'll build a command-line dashboard that fetches country data from the free REST Countries API and presents it neatly.

"""
country_dashboard.py — Fetch and display country info from REST Countries API.
"""
import requests
import json


def fetch_country(name):
    """Fetch country data by name. Returns dict or None."""
    url = f"https://restcountries.com/v3.1/name/{name}"
    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        countries = response.json()
        return countries[0]  # Take first match
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            print(f"❌ Country '{name}' not found.")
        else:
            print(f"❌ HTTP error: {e.response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"❌ Request failed: {e}")
    return None


def display_country(country):
    """Pretty-print country information."""
    name = country["name"]["common"]
    official = country["name"]["official"]
    capital = ", ".join(country.get("capital", ["N/A"]))
    region = country.get("region", "N/A")
    subregion = country.get("subregion", "N/A")
    population = country.get("population", 0)
    area = country.get("area", 0)
    languages = ", ".join(country.get("languages", {}).values())
    currencies = ", ".join(
        f"{c['name']} ({c.get('symbol', '')})"
        for c in country.get("currencies", {}).values()
    )
    flag = country.get("flag", "")

    print(f"\n{'=' * 50}")
    print(f"  {flag}  {name}")
    print(f"{'=' * 50}")
    print(f"  Official Name : {official}")
    print(f"  Capital       : {capital}")
    print(f"  Region        : {region} / {subregion}")
    print(f"  Population    : {population:,}")
    print(f"  Area          : {area:,.0f} km²")
    print(f"  Languages     : {languages}")
    print(f"  Currencies    : {currencies}")
    print(f"{'=' * 50}")


def compare_countries(names):
    """Fetch and compare multiple countries side by side."""
    countries = []
    for name in names:
        c = fetch_country(name)
        if c:
            countries.append(c)

    if len(countries) < 2:
        print("Need at least 2 valid countries to compare.")
        return

    print(f"\n{'':>20}", end="")
    for c in countries:
        print(f"{c['name']['common']:>20}", end="")
    print()
    print("-" * (20 + 20 * len(countries)))

    # Population
    print(f"{'Population':>20}", end="")
    for c in countries:
        print(f"{c.get('population', 0):>20,}", end="")
    print()

    # Area
    print(f"{'Area (km²)':>20}", end="")
    for c in countries:
        print(f"{c.get('area', 0):>20,.0f}", end="")
    print()

    # Region
    print(f"{'Region':>20}", end="")
    for c in countries:
        print(f"{c.get('region', 'N/A'):>20}", end="")
    print()

    # Capital
    print(f"{'Capital':>20}", end="")
    for c in countries:
        cap = ", ".join(c.get("capital", ["N/A"]))
        print(f"{cap:>20}", end="")
    print()


def main():
    """Interactive country dashboard."""
    print("🌍 Country Info Dashboard")
    print("Commands: search, compare, quit\n")

    while True:
        command = input(">>> ").strip().lower()

        if command == "quit":
            print("Goodbye! 👋")
            break
        elif command == "search":
            name = input("Country name: ").strip()
            country = fetch_country(name)
            if country:
                display_country(country)
        elif command == "compare":
            names = input("Countries (comma-separated): ").strip()
            name_list = [n.strip() for n in names.split(",")]
            compare_countries(name_list)
        else:
            print("Unknown command. Try: search, compare, quit")


if __name__ == "__main__":
    main()

🌍 Country Info Dashboard
Commands: search, compare, quit

>>> search
Country name: philippines

==================================================
  🇵🇭  Philippines
==================================================
  Official Name : Republic of the Philippines
  Capital       : Manila
  Region        : Asia / South-Eastern Asia
  Population    : 109,581,078
  Area          : 342,353 km²
  Languages     : English, Filipino
  Currencies    : Philippine peso (₱)
==================================================

>>> compare
Countries (comma-separated): japan, south korea, philippines

                           Japan         South Korea         Philippines
------------------------------------------------------------------------
          Population 125,836,021          51,269,185         109,581,078
        Area (km²)       377,930             100,210             342,353
              Region        Asia                Asia                Asia
             Capital       Tokyo               Seoul              Manila

>>> quit
Goodbye! 👋

💪 Hands-on Exercises

import requests


def search_books(query, limit=5):
    """Search Open Library and return a list of book dicts."""
    url = "https://openlibrary.org/search.json"
    params = {"q": query, "limit": limit}

    try:
        response = requests.get(url, params=params, timeout=15)
        response.raise_for_status()
        data = response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching books: {e}")
        return []

    books = []
    for doc in data.get("docs", []):
        books.append({
            "title": doc.get("title", "Unknown Title"),
            "author": ", ".join(doc.get("author_name", ["Unknown"])),
            "year": doc.get("first_publish_year", "N/A"),
        })
    return books


def main():
    query = input("Search for a book: ").strip()
    if not query:
        print("No search term provided.")
        return

    print(f"\nSearching for '{query}'...\n")
    results = search_books(query)

    if not results:
        print("No results found.")
        return

    for i, book in enumerate(results, 1):
        print(f"  {i}. {book['title']}")
        print(f"     by {book['author']} ({book['year']})")


if __name__ == "__main__":
    main()

import requests

GITHUB_API = "https://api.github.com"
HEADERS = {"User-Agent": "PythonCourseLearner/1.0"}


def get_user(username):
    """Fetch GitHub user profile."""
    url = f"{GITHUB_API}/users/{username}"
    response = requests.get(url, headers=HEADERS, timeout=10)
    response.raise_for_status()
    return response.json()


def get_repos(username, count=5):
    """Fetch user's most recently updated repos."""
    url = f"{GITHUB_API}/users/{username}/repos"
    params = {"sort": "updated", "per_page": count}
    response = requests.get(
        url, headers=HEADERS, params=params, timeout=10
    )
    response.raise_for_status()
    return response.json()


def display_profile(username):
    """Display a GitHub user profile and recent repos."""
    try:
        user = get_user(username)
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            print(f"User '{username}' not found.")
        else:
            print(f"Error: {e.response.status_code}")
        return
    except requests.exceptions.RequestException as e:
        print(f"Connection error: {e}")
        return

    print(f"\n👤 {user.get('name', username)}")
    print(f"   @{user['login']}")
    if user.get("bio"):
        print(f"   {user['bio']}")
    if user.get("location"):
        print(f"   📍 {user['location']}")
    print(f"   📦 {user['public_repos']} public repos")
    print(f"   👥 {user['followers']} followers")

    try:
        repos = get_repos(username)
    except requests.exceptions.RequestException:
        print("   (Could not fetch repos)")
        return

    print(f"\n   🔄 Recently Updated Repos:")
    for repo in repos:
        lang = repo.get("language") or "—"
        stars = repo["stargazers_count"]
        desc = repo.get("description") or "No description"
        print(f"   ⭐ {stars:>4}  {repo['name']} [{lang}]")
        print(f"         {desc[:60]}")


if __name__ == "__main__":
    username = input("GitHub username: ").strip()
    if username:
        display_profile(username)

📝 Summary

In this lesson you learned to connect Python programs to the outside world through REST APIs. Here's what we covered:

• APIs are interfaces that let programs talk to servers — REST APIs use HTTP methods and JSON
• The requests library provides a clean, intuitive API for HTTP: get(), post(), put(), patch(), delete()
• JSON maps directly to Python dicts and lists — use response.json() or the json module
• Query parameters go in the params= argument; custom headers go in headers=
• POST with json= sends data; the server typically returns 201 Created
• Authentication uses API keys (in params or headers) or Bearer tokens — keep secrets in environment variables
• Error handling means catching Timeout, ConnectionError, and HTTPError, plus always setting timeout=
• Retry logic with exponential backoff handles transient failures gracefully

🔑 Quick Reference

📚 Additional Resources

• requests Documentation
• Python Docs — json Module
• httpbin.org — HTTP Testing Service
• JSONPlaceholder — Fake REST API
• REST Countries API
• Public APIs List — Massive Collection of Free APIs

🚀 What's Next?

In the next lesson, we'll learn Database Basics with SQLite — SQL fundamentals, Python's sqlite3 module, parameterized queries, and building data-backed applications. Combined with APIs, you'll be able to fetch data from the web and store it locally.