Capstone: a complete API

Order of checks on each request

An airport runs its checks in a fixed order: passport first, then boarding pass, then your bag, and only then the gate. Nobody inspects your luggage before they know you're allowed to travel. An API needs the same discipline, both for security and for clear errors:

1. Route: does the method and path exist? (404 or 405)
2. Authenticate: is there a valid key? (401). Do this before anything that touches data.
3. Authorize the action: does the key have the scope? (403)
4. Validate input: the body, the query parameters, the cursor. (422 or 400)
5. Load and check objects: does the product exist? Is this review the caller's? (404)
6. Do the work in one transaction, and build the response.

Checking the scope before validating means an unauthorized caller learns nothing about your schemas. Validating before touching the database means bad input never reaches SQL.

In plain words: ask "who are you?" and "may you do this?" before you look at anything they sent.

KEYS = {"key-123"}
PRODUCTS = {7: "Tent"}

def wrong_order(key, product_id):
    if product_id not in PRODUCTS:
        return 404
    if key not in KEYS:
        return 401
    return 200

def right_order(key, product_id):
    if key not in KEYS:
        return 401
    if product_id not in PRODUCTS:
        return 404
    return 200

for pid in [7, 8]:
    print("product", pid, "wrong order:", wrong_order(None, pid), " right order:", right_order(None, pid))

def check(has_key, valid_body):
    if not has_key: return 401
    if not valid_body: return 422
    return 200
print(check(False, False))

One entry point, many tests

The whole service is a class with one method, handle(method, path, headers, body), returning (status, headers, body). Picture one front counter that every request walks up to. Production wraps it in a real server, as you saw with WSGI. Tests walk up to the same counter directly, with an in-memory database, so every requirement in the table above becomes a one-line check.

class Pinger:
    def __init__(self, keys):
        self.keys = keys

    def handle(self, method, path, headers, body=None):
        if (method, path) != ("GET", "/ping"):
            return 404, {}, {"error": {"type": "not_found_error", "message": "no such route"}}
        key = headers.get("authorization", "").removeprefix("Bearer ")
        if key not in self.keys:
            return 401, {}, {"error": {"type": "authentication_error", "message": "bad key"}}
        return 200, {}, {"pong": self.keys[key]}

api = Pinger({"k_ada": "ada"})
tests = [
    (("GET", "/ping", {"authorization": "Bearer k_ada"}), 200),
    (("GET", "/ping", {}), 401),
    (("GET", "/pong", {"authorization": "Bearer k_ada"}), 404),
]
for args, want in tests:
    got = api.handle(*args)[0]
    print("PASS" if got == want else "FAIL", args[:2], got)

Before you call it done

Pilots read a checklist before every flight, however many hours they've flown. Here's a review checklist for any API you build:

• Every endpoint authenticates, checks scopes, and checks object ownership.
• Every input is validated, and every error uses the one error shape.
• Lists are paginated with a limit cap; nothing returns unbounded data.
• Writes that clients may retry accept idempotency keys.
• SQL uses placeholders, and any column names come from allowlists.
• Responses carry request ids; logs are structured and free of secrets.
• There's an OpenAPI spec, and CI runs the tests and a breaking-change check.

The exercise builds the core of the reviews API. Helpers from earlier lessons are provided in compact form, so you can focus on putting them together correctly.

Mistakes this project is designed to catch

Don't validate before you authorize. A door guard shouldn't explain what's wrong with your fake ID. If an unauthorized caller gets a detailed list of what's wrong with their request, you've taught a stranger how your API works. Check the scope first, then validate.

403 can confirm that something exists. A clerk who says "I can't show you that file" has told you there's a file. If a user asks for someone else's order and gets 403, they've learned that the order exists. Answer 404, exactly as if it didn't, and no one can use your API to probe for valid ids.

Keep idempotency keys per client. Two restaurants can hand out the same ticket number, and neither should give you the other's meal. If two clients happen to use the same key and you share a single list, the second client receives the first client's response, which might include someone else's data. Store each key along with the client it belongs to.

Don't count rows to find out if there are more. To learn whether a book has another page, you turn one page. You don't count the rest. SELECT COUNT(*) on a large table is slow, and you only need a yes or no. Ask for one row more than the page size. If it comes back, there's another page, and you drop it from the response. It's a small trick that works at any size.

One test per rule

Each rule in the brief deserves its own test, so a failure tells you exactly what broke.