HTTP clients and APIs

Past the basics: the intro tutorials’s API taster. You will call REST-style endpoints with requests, handle failures cleanly, and structure code so swapping test doubles in is straightforward.

Install and basic GET

pip install requests

import requests

response = requests.get(
    "https://api.example.com/users/1",
    timeout=10,
)
response.raise_for_status()
user = response.json()
print(user["email"])

Always set a timeout. Without one, a hung remote server hangs your program indefinitely.

Headers, auth, and POST JSON

headers = {"Authorization": "Bearer YOUR_TOKEN"}
payload = {"name": "Alice", "role": "editor"}

response = requests.post(
    "https://api.example.com/users",
    json=payload,
    headers=headers,
    timeout=10,
)
response.raise_for_status()

Passing json=payload sets the body and Content-Type for you. Do not hand-serialise unless you have a reason.

Wrap calls in a small client class

A thin wrapper centralises base URL, auth, and error handling.

class ExampleApi:
    def __init__(self, base_url: str, token: str) -> None:
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers["Authorization"] = f"Bearer {token}"

    def get_user(self, user_id: int) -> dict:
        url = f"{self.base_url}/users/{user_id}"
        response = self.session.get(url, timeout=10)
        response.raise_for_status()
        return response.json()

Handle HTTP errors explicitly

from requests import HTTPError, RequestException

try:
    user = api.get_user(404)
except HTTPError as exc:
    if exc.response is not None and exc.response.status_code == 404:
        print("User not found")
    else:
        raise
except RequestException as exc:
    raise RuntimeError("network failure") from exc

Pagination and rate limits

Many APIs return pages of results and throttle aggressive clients. Read the docs, respect Retry-After headers, and sleep between bulk requests.

import time

def fetch_all_pages(api, path: str) -> list[dict]:
    results = []
    url = path
    while url:
        data = api.session.get(url, timeout=10).json()
        results.extend(data["items"])
        url = data.get("next")
        time.sleep(0.2)
    return results

Testing without hitting the network

Use responses or mock the session in pytest. Your tests should not depend on a third-party API being online.

Next: structured database access with SQLAlchemy or plain DB-API – the layer between your Python and persistent data.