REST APIs — GET Requests Deep Dive

• Spot the four parts of a REST URL: scheme, host, path, query.
• Pass query parameters with the params= kwarg (safer than f-string concatenation).
• Read response headers — Content-Type, X-RateLimit, Cache-Control.
• Decode status codes into the right reaction.

https://api.github.com/repos/python/cpython/issues?state=open&per_page=5
└──┬──┘   └────┬──────┘└────────────┬───────┘└─────────────┬─────────┘
scheme       host                  path                   query

Four parts. Most APIs use the same shape:

• Path parameters identify which resource — /repos/python/cpython/issues.
• Query parameters modify the request — state=open, per_page=5.

Query parameters with params=

NEVER build the URL with string concatenation. Pass a dict to params=:

import requests

r = requests.get(
    "https://api.github.com/repos/python/cpython/issues",
    params={"state": "open", "per_page": 5},
    timeout=10,
)
print(r.url)          # → https://api.github.com/.../issues?state=open&per_page=5
issues = r.json()
print(f"got {len(issues)} issues")
for it in issues:
    print(f"  #{it['number']:>5}  {it['title']}")

The dict is URL-encoded for you — spaces, special characters, all safe.

Path parameters with f-strings

When part of the URL identifies the resource (a username, a country code), use an f-string:

username = "torvalds"
r = requests.get(f"https://api.github.com/users/{username}", timeout=5)
print(r.json()["public_repos"])

Useful response headers

print(r.headers["Content-Type"])       # → application/json; charset=utf-8
print(r.headers.get("X-RateLimit-Remaining"))   # → "59"
print(r.headers.get("Date"))           # → "Thu, 28 May 2026 06:33:14 GMT"

Headers tell you the response's shape (Content-Type), the API's rules (X-RateLimit-*), and metadata (Date). Use .get() for headers that may be missing.

Status code → action

200  OK              → use the body
201  Created         → POST succeeded
204  No Content      → success, no body
301  Moved           → follow the new URL
400  Bad Request     → your inputs were wrong
401  Unauthorized    → missing or bad token
403  Forbidden       → token has no rights here
404  Not Found       → wrong URL
429  Too Many        → slow down (rate limit)
500  Server Error    → not your fault, maybe retry
503  Unavailable     → temporary outage

The simplest rule: r.raise_for_status() turns any 4xx or 5xx into an exception. Catch it and choose what to do.

# stars.py — list a user's top 5 repos by stars
import requests

USERNAME = "fastapi"   # try any GitHub user/org

r = requests.get(
    f"https://api.github.com/users/{USERNAME}/repos",
    params={"sort": "stars", "direction": "desc", "per_page": 5},
    headers={"Accept": "application/vnd.github+json"},
    timeout=10,
)
r.raise_for_status()
repos = r.json()

remaining = r.headers.get("X-RateLimit-Remaining", "?")
print(f"⭐ Top repos for {USERNAME}   ({remaining} req remaining this hour)")
print("-" * 50)
for repo in repos:
    print(f"  {repo['stargazers_count']:>7}  {repo['name']}")

Sample output

⭐ Top repos for fastapi   (54 req remaining this hour)
--------------------------------------------------
    78934  fastapi
     5012  typer
     3287  sqlmodel
      902  asyncer
      431  full-stack-fastapi-template

Read the diff

Three deliberate choices: params= instead of f-string building, headers=Accept to tell GitHub which API version we expect, and reading X-RateLimit-Remaining to know how many more calls we can make this hour. That last one matters — burning your rate budget mid-loop is a classic junior mistake.

Path parameters identify the resource; query parameters refine it. Use params= to add queries safely. Headers carry metadata you can read (Content-Type, X-RateLimit). Status codes tell you what to do — raise_for_status() is the safety belt. Tomorrow we send data with POST.