Working with APIs in Python

The Story That Explains APIs

Every modern app talks to APIs — weather, payments, maps, AI models, stock prices, social feeds. In Python, the standard tool is the requests library. You send HTTP calls in one line, parse JSON in one line, and you're done. This tutorial takes you from "what is an API" to "I can build a resilient client for a real service" with diagrams and runnable examples.

Visual Diagram — The HTTP Request / Response Cycle

The Three Building Blocks of an API Call

Your First API Call

# pip install requests
import requests

# Public API — no auth required
r = requests.get("https://api.github.com/users/torvalds")

print(r.status_code)          # 200 = success
print(r.headers["Content-Type"]) # application/json; charset=utf-8

data = r.json()               # parse JSON → Python dict
print(data["name"])
print(data["public_repos"])
print(data["bio"])

The HTTP Methods — What They Mean, When to Use Each

import requests

BASE = "https://jsonplaceholder.typicode.com"   # public sandbox API

# GET — read one post
r = requests.get(f"{BASE}/posts/1", timeout=5)
print(r.json()["title"])

# POST — create a new post
new_post = {"title": "Hello", "body": "World", "userId": 1}
r = requests.post(f"{BASE}/posts", json=new_post, timeout=5)
print(r.status_code, r.json())

# PUT — replace an existing post
r = requests.put(f"{BASE}/posts/1",
                 json={"id": 1, "title": "Updated", "body": "New", "userId": 1},
                 timeout=5)

# PATCH — change only the title
r = requests.patch(f"{BASE}/posts/1", json={"title": "Just the title"}, timeout=5)

# DELETE — remove
r = requests.delete(f"{BASE}/posts/1", timeout=5)
print(r.status_code)   # 200 or 204

Query Params vs Request Body — When to Use Which

There are two places to send data with a request: the URL (query string) or the body. Getting this wrong is the #1 source of "why won't my POST work" frustration.

import requests

# Query params — passed via params={}
r = requests.get(
    "https://api.open-meteo.com/v1/forecast",
    params={
        "latitude": 35.68,
        "longitude": 139.65,
        "current_weather": True,
    },
    timeout=5,
)
# The URL sent becomes:
#   .../forecast?latitude=35.68&longitude=139.65&current_weather=True
print(r.url)

# JSON body — passed via json={}
r = requests.post(
    "https://httpbin.org/post",
    json={"name": "Ada", "role": "engineer"},
    timeout=5,
)
print(r.json()["json"])   # httpbin echoes back what you sent

Parsing JSON — The Most Common Response Format

~95% of modern APIs speak JSON. requests parses it in one method call — the returned Python object is a normal dict / list tree.

import requests

r = requests.get("https://api.github.com/repos/python/cpython", timeout=5)
data = r.json()             # dict[str, Any]

print(data["full_name"])       # python/cpython
print(data["stargazers_count"]) # 62000+
print(data["language"])        # Python
print(data["license"]["name"]) # nested access is just dict[key]

# Nested / lists in JSON — same rules as normal Python
r = requests.get("https://api.github.com/repos/python/cpython/contributors",
                 params={"per_page": 3}, timeout=5)
for contributor in r.json():
    print(f"{contributor['login']:15s}  {contributor['contributions']} commits")

Safe Access to Optional Keys

# The bio might be missing — .get() returns None instead of crashing
bio = data.get("bio")                       # None if missing
bio = data.get("bio", "no bio available")   # custom default

# Nested optional access — walrus + get chains
license_name = (data.get("license") or {}).get("name", "unknown")

Parsing XML — For Legacy & Enterprise APIs

XML still lives on in older or enterprise services — SOAP endpoints, government data feeds, RSS/Atom, some payment gateways. Python's standard library handles it with xml.etree.ElementTree. For untrusted XML, use defusedxml instead to block XXE attacks.

import requests
import xml.etree.ElementTree as ET

# Example: NASA's Astronomy Picture of the Day feed (RSS/XML)
r = requests.get("https://www.nasa.gov/feed/", timeout=5)
root = ET.fromstring(r.content)     # root is the outermost <rss> element

# RSS structure: rss > channel > item*
channel = root.find("channel")
for item in channel.findall("item")[:3]:
    title = item.findtext("title")
    link  = item.findtext("link")
    date  = item.findtext("pubDate")
    print(f"• {title}\n  {link}\n  {date}\n")

Authentication — Proving Who You Are

Most useful APIs require you to identify yourself. There are three common patterns. In every case, credentials belong in environment variables — never in code, never in git.

import os, requests

# 1) API key as query param — the API tells you the parameter name
r = requests.get(
    "https://api.openweathermap.org/data/2.5/weather",
    params={"q": "Mumbai", "appid": os.environ["OWM_KEY"]},
    timeout=5,
)

# 2) API key as header — many modern APIs prefer this
r = requests.get(
    "https://api.example.com/data",
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=5,
)

# 3) Bearer token — GitHub, OpenAI, Stripe pattern
token = os.environ["GITHUB_TOKEN"]
r = requests.get(
    "https://api.github.com/user",
    headers={"Authorization": f"Bearer {token}"},
    timeout=5,
)

# 4) Basic auth — requests has built-in support
r = requests.get(
    "https://api.example.com/private",
    auth=(os.environ["USER"], os.environ["PASSWORD"]),
    timeout=5,
)

Handling Status Codes & Errors

The status code is your first check on every response. Ignoring it is how you end up with cryptic bugs at 3 AM.

import requests

r = requests.get("https://api.github.com/repos/does-not/exist", timeout=5)

# Option A: check the code manually
if r.status_code == 200:
    print(r.json())
elif r.status_code == 404:
    print("repo does not exist")
elif r.status_code == 429:
    print("rate limited, wait and retry")
else:
    print(f"unexpected: {r.status_code}")

# Option B: let requests raise on any 4xx/5xx
try:
    r = requests.get("https://api.github.com/repos/does-not/exist", timeout=5)
    r.raise_for_status()          # raises HTTPError on non-2xx
    data = r.json()
except requests.HTTPError as e:
    print(f"HTTP failure: {e}")
except requests.Timeout:
    print("server took too long")
except requests.ConnectionError:
    print("can't reach server (DNS / offline)")

Retries with Exponential Backoff

Networks fail. Servers hiccup. Rate limits happen. Any real client retries transient errors with an increasing delay so the target has room to recover — this is called exponential backoff.

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

# Built-in retry — no manual loop needed
retry_policy = Retry(
    total=5,                     # at most 5 attempts
    backoff_factor=1.0,           # delays: 1s, 2s, 4s, 8s, 16s
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "POST"],
    respect_retry_after_header=True,
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry_policy))

# Now every request through this session auto-retries transient errors
r = session.get("https://api.github.com/users/torvalds", timeout=10)
print(r.status_code)

Sessions — Connection Pooling for Speed

If you make more than one request to the same host, use a Session. It reuses the underlying TCP + TLS connection — the second request is dramatically faster because it skips the DNS lookup, TCP handshake, and TLS negotiation.

import requests

# Bad — new connection every call
for i in range(100):
    requests.get(f"https://api.github.com/repos/python/cpython/issues/{i}")

# Good — one session, connections reused
with requests.Session() as s:
    s.headers.update({"Authorization": f"Bearer {token}"})
    for i in range(100):
        r = s.get(f"https://api.github.com/repos/python/cpython/issues/{i}",
                  timeout=5)

Pagination — Fetching Big Result Sets

APIs return data in pages — you rarely get 10,000 items in one call. Two common patterns:

def fetch_all_issues(repo: str, token: str) -> list[dict]:
    session = requests.Session()
    session.headers.update({"Authorization": f"Bearer {token}"})

    all_issues, page = [], 1
    while True:
        r = session.get(f"https://api.github.com/repos/{repo}/issues",
                       params={"page": page, "per_page": 100, "state": "all"},
                       timeout=10)
        r.raise_for_status()
        batch = r.json()
        if not batch:                    # empty page = we're done
            break
        all_issues.extend(batch)
        page += 1
    return all_issues

issues = fetch_all_issues("python/cpython", os.environ["GITHUB_TOKEN"])
print(f"fetched {len(issues)} issues")

Common Pitfalls (and Fixes)

Real-World Example — Complete GitHub Repo Analyzer

All the pieces together: session, auth, timeout, retries, error handling, JSON parsing, and pagination — in one production-ready client.

import os
from dataclasses import dataclass
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

BASE = "https://api.github.com"

@dataclass(frozen=True)
class RepoStats:
    full_name: str
    stars: int
    forks: int
    open_issues: int
    language: str | None
    top_contributors: list[str]

def build_session(token: str) -> requests.Session:
    retry = Retry(total=5, backoff_factor=1.0,
                  status_forcelist=[429, 500, 502, 503, 504])
    s = requests.Session()
    s.mount("https://", HTTPAdapter(max_retries=retry))
    s.headers.update({
        "Authorization": f"Bearer {token}",
        "Accept":        "application/vnd.github+json",
        "User-Agent":    "repo-analyzer/1.0",
    })
    return s

def analyze_repo(session: requests.Session, repo: str) -> RepoStats | None:
    try:
        r = session.get(f"{BASE}/repos/{repo}", timeout=10)
        r.raise_for_status()
        info = r.json()

        c = session.get(f"{BASE}/repos/{repo}/contributors",
                       params={"per_page": 5}, timeout=10)
        c.raise_for_status()
        top = [u["login"] for u in c.json()]

        return RepoStats(
            full_name        = info["full_name"],
            stars            = info["stargazers_count"],
            forks            = info["forks_count"],
            open_issues      = info["open_issues_count"],
            language         = info.get("language"),
            top_contributors = top,
        )
    except requests.HTTPError as e:
        print(f"[{repo}] HTTP error: {e}")
    except (requests.Timeout, requests.ConnectionError):
        print(f"[{repo}] network problem")
    return None

# ── Run it ──────────────────────────────────────────────
REPOS = ["python/cpython", "pallets/flask", "psf/requests"]
with build_session(os.environ["GITHUB_TOKEN"]) as s:
    for repo in REPOS:
        stats = analyze_repo(s, repo)
        if stats:
            print(f"\n{stats.full_name}")
            print(f"  ★ {stats.stars:,}   forks {stats.forks:,}   issues {stats.open_issues:,}")
            print(f"  language: {stats.language}")
            print(f"  top:      {', '.join(stats.top_contributors)}")

Golden Rules