Day 41 · Ordering at the counter

HTTP & Build Your First API

You will be able to

Dissect an HTTP request and response: method, path, headers, status, body
Choose correct methods and status codes for CRUD-style operations
Use httpx to call APIs with params, headers, timeouts, and error handling
Build a FastAPI service with path/query parameters and pydantic validation
Explore your own API through its auto-generated docs

Today's ~120 minutes

Spaced-rep warm-up: due cards (async, GIL, semaphores)	10 min
ELI5 + tech read; trace one request through the http-cycle visualizer	18 min
Guided: build the counter, then be the customer	42 min
Practice: the resilient client	20 min
Project: quotes API + client	20 min
Quiz + flashcards	10 min

Builds on: Day 40 — Concurrency & async · Day 10 — OOP II — dataclasses (pydantic's shape) · Day 5 — JSON handling

The analogy

🧸 ELI5⚙ Tech

A coffee counter has a protocol everyone silently knows. You state a VERB and a THING: "GET me a latte." The barista replies with a STATUS before anything else — "coming up" (all good), "we don't have that" (your mistake), "the machine is broken" (their mistake) — and then, maybe, the drink. You can also hand things over: "POST: here's my custom order form." Neither of you remembers the last exchange; every order is complete in itself, which is why you repeat "for Priya, oat milk" every single time.

HTTP is exactly this, written down. The request line says the verb and the thing (GET /books/7); headers are the sticky notes on the order ("I speak JSON", "I'm Priya"); the body is the form you handed over. The response leads with a three-digit status — 2xx coming-up, 4xx your-mistake, 5xx our-mistake — then its own headers and body. Statelessness is the counter's amnesia: every request must carry everything needed to serve it.

Today you stand on BOTH sides of the counter: morning as the customer (httpx, the caller), afternoon as the barista (FastAPI, the server) — and the customer half is how you will talk to every LLM API for the rest of the program.

Why this matters on the job

HTTP is the substrate of your entire future stack: every LLM call (Day 106) is an HTTP POST, every 429 you retry (Day 107), every webhook, every RAG service endpoint. Building the server side is just as core: the AI features you ship are consumed as APIs, and FastAPI is the Python default — async-native (yesterday's loop, now serving requests), pydantic-validated (the same contract thinking as Day 36's schemas, at the door of your service), with free interactive docs your customers and teammates will actually use. The Day 42 checkpoint, the Day 49 URL shortener, and the capstone's serving layer are all today's skeleton, thickened.

Watch it happen

Ordering at the counter — one HTTP request, end to end

step 1 / 6

Browserclient→DNSphonebook→Serverapi.shop.com→Responsestatus + body

✉ GET https://api.shop.com/orders

You ask for a URL. Before anything can be ordered, the browser needs the server's street address — domain names are for humans, not routers.

🎯 Predict modespeed1×

Guided practice

guided 1

Stand up the counter (FastAPI)

22 min

Install the day's tools in your venv: pip install fastapi uvicorn httpx. Create api.py from the starter — an in-memory books API (dict for storage; real persistence arrives tomorrow).
Run uvicorn api:app --reload and open http://127.0.0.1:8000/docs. Click through the auto-docs: expand GET /books, try it, read the curl it generated. This page came entirely from your type hints.
Poke the validation without writing any client code: try GET /books/abc (422 — path type failed), POST a book with a negative price (422 with a field-level error message locating exactly what and where), then a valid POST (201, echoing the created resource with its id).
Read the starter's status-code choices out loud and justify each: 201 for create, 404 for missing id, 422 arriving free from pydantic. Then add a DELETE route yourself returning 204 — and confirm in /docs that it appeared.
Watch the uvicorn console as you click: every line is method, path, status — the request log you will grep in production (Day 16 pays off here).

🐍 python — editable, runs in your browser

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(title="Books API", version="0.1.0")

class BookIn(BaseModel):
    title: str = Field(min_length=1)
    author: str = Field(min_length=1)
    price: float = Field(ge=0)          # the contract at the door
    year: int | None = None

class Book(BookIn):
    id: int

_db: dict[int, Book] = {}
_next_id = 1

@app.get("/books")
def list_books(author: str | None = None, limit: int = 10) -> list[Book]:
    books = list(_db.values())          # author & limit are query params
    if author:
        books = [b for b in books if b.author == author]
    return books[:limit]

@app.get("/books/{book_id}")
def get_book(book_id: int) -> Book:     # /books/abc -> 422, automatically
    if book_id not in _db:
        raise HTTPException(status_code=404, detail="book not found")
    return _db[book_id]

@app.post("/books", status_code=201)
def create_book(book: BookIn) -> Book:  # body parsed & validated by pydantic
    global _next_id
    created = Book(id=_next_id, **book.model_dump())
    _db[_next_id] = created
    _next_id += 1
    return created

# your turn: DELETE /books/{book_id} -> 204, or 404 if missing

Ctrl/⌘+Enter runs · Tab indents · numpy/pandas/sklearn auto-load on import (torch and network calls need a local run)

guided 2

Be the customer (httpx)

20 min

With the server still running, create client.py. Use one httpx.Client(base_url=..., timeout=5.0) for all calls (connection reuse — and a timeout, always).
POST three books, then GET the list with params={"author": ..., "limit": 2} — print the URL httpx actually built (response.request.url) to see query-string encoding done for you.
Handle failure tiers properly: GET /books/999 and branch on status_code — 404 is not an exception at transport level, and blind .json()["title"] on it would KeyError. Then use raise_for_status() in a try/except as the alternative style; print status_code and the error body from the exception.
Inspect a full exchange: print request method/URL/headers and response status/headers (find content-type and content-length). Match each piece to the request-anatomy diagram from the tech section.
Finish with the async version: rewrite the three POSTs with httpx.AsyncClient and asyncio.gather — yesterday's pattern, today against a real server. Time sequential vs gathered.

🐍 python — editable, runs in your browser

import asyncio, time
import httpx

BASE = "http://127.0.0.1:8000"

with httpx.Client(base_url=BASE, timeout=5.0) as client:
    for t, a, p in [("Deep Work", "Cal Newport", 14.99),
                    ("Digital Minimalism", "Cal Newport", 12.99),
                    ("Refactoring", "Martin Fowler", 47.99)]:
        r = client.post("/books", json={"title": t, "author": a, "price": p})
        r.raise_for_status()
        print("created:", r.status_code, r.json()["id"])

r = client.get("/books", params={"author": "Cal Newport", "limit": 2})
    print("url built:", r.request.url)
    print("status:", r.status_code, "content-type:", r.headers["content-type"])
    for book in r.json():
        print("  ", book["title"])

r = client.get("/books/999")
    if r.status_code == 404:                 # transport succeeded; API said no
        print("as expected:", r.status_code, r.json()["detail"])

async def create_many():
    async with httpx.AsyncClient(base_url=BASE, timeout=5.0) as ac:
        t0 = time.perf_counter()
        payloads = [{"title": f"Vol {i}", "author": "Bulk", "price": 1.0}
                    for i in range(20)]
        rs = await asyncio.gather(*(ac.post("/books", json=p) for p in payloads))
        print(f"20 concurrent creates: {time.perf_counter() - t0:.2f}s,",
              "all 201:", all(r.status_code == 201 for r in rs))

asyncio.run(create_many())

Ctrl/⌘+Enter runs · Tab indents · numpy/pandas/sklearn auto-load on import (torch and network calls need a local run)

On your own

The resilient client

20 min

Make your API flaky, then build the client that survives it. Add GET /flaky to api.py: 30% of calls return 503, 20% return 429 with a Retry-After: 1 header, the rest 200. Then write resilient.py: a get_with_retries(client, url, max_tries=4) function implementing exponential backoff with jitter (0.5s base, doubling, plus random 0–0.3s), honoring Retry-After when present, retrying ONLY retryable statuses (429, 502, 503 — never 404), and logging each attempt with its wait. Prove it: 50 calls through the wrapper should all eventually succeed; print the attempt histogram.

Constraints: timeouts on every call; a final failure after max_tries raises a clear exception. Think: why is retrying a GET always safe, and when would retrying a POST double-charge someone?

Hints: wait = base * 2**attempt + random.uniform(0, 0.3); Retry-After arrives as seconds in r.headers.

Ship before you stop

Quotes API — designed, built, documented

Design and build quotes_api.py solo: a quotes service with POST /quotes (text, author, tags list — validated: non-empty text, at most 5 tags), GET /quotes (filterable by author and tag via query params, with limit/offset pagination), GET /quotes/{id}, DELETE /quotes/{id}, and GET /quotes/random. Correct status codes throughout (201/204/404/422). Then ship quotes_client.py exercising every route including the failure paths, using one Client with timeout. Screenshot or describe your /docs page in the README section. In-memory storage is fine — tomorrow it grows a real database and tests. Commit both files.

Rubric — check what you completed (0/5)

All six routes work and return the specified status codes (checked via client, not just /docs)Pydantic rejects empty text and >5 tags with 422 field-level errorsPagination works: limit/offset slices verified with 10+ seeded quotesClient demonstrates the 404 branch and one validation failure without crashingEvery client call sets a timeout; committed with a README note on your status-code choices

Common mistakes & misconceptions

No timeout on HTTP calls. The default is to wait forever; one hung upstream hangs your service. timeout= on every client — non-negotiable from today.
Assuming a 2xx because no exception was raised. httpx returns 404s and 500s as normal responses — check status_code or call raise_for_status().
Using GET for state-changing actions ("GET /books/7/delete"). Crawlers, prefetchers, and retries will happily fire it repeatedly — verbs carry contracts.
Returning 200 with {"error": "not found"} in the body. Clients branch on status codes; lying with 200 breaks every generic client, cache, and monitor downstream.
Blocking inside an async def handler (sync DB call, time.sleep) — yesterday's cardinal sin, now freezing every concurrent request your server is juggling.
Retrying non-idempotent POSTs blindly on timeout — the request may have succeeded before the timeout hit: double-charge. Retry idempotent calls freely; POSTs need idempotency keys (Day 107).

Knowledge check

Q1. A client sends valid JSON to your FastAPI route, but price is -5 against Field(ge=0). What does FastAPI return?

Q2. Which request is safe to retry automatically after a timeout, and why?

Q3. Your service calls a dependency that starts returning 503. The well-behaved client response is…

Go deeper — curated resources

docsMDN — An overview of HTTP ↗20 min docsFastAPI — official tutorial (first steps through body validation) ↗30 min docshttpx — official documentation (quickstart) ↗15 min

If you have a third hour

FastAPI — async def vs def routes ↗ — Read how FastAPI runs plain-def handlers in a threadpool but async handlers on the loop — then connect it to yesterday's blocking-call sin and decide which your DB calls need tomorrow.

Done means

Books API serving with /docs explored; DELETE route added and verified
Client handles 404 and validation-failure branches without crashing
Resilient wrapper survives 50 flaky calls with logged backoff
Quotes API + client committed with correct status codes throughout
Quiz ≥ 2/3

How this connects

← Back: Handlers run on Day 40's event loop (its cardinal sin now a serving outage); pydantic models are Day 10's dataclasses with Day 36's contract enforcement; the JSON bodies are Day 5's serialization on the wire.

Forward →: Tomorrow this API gains a real database and TestClient tests. Day 43 opens the network layers beneath it, Day 44 adds auth, Day 45 hardens the architecture — and Day 106's LLM calls are exactly today's httpx POSTs with an Authorization header.

Unlocks: D42 Week 6 Checkpoint: API + DB Mini-Service · D43 Networking — Packets to HTTPS · D44 Security, AuthN & AuthZ · D68 Cleaning & Validation