6.1 Learning Objectives🔗

By the end of this lecture you should be able to:

1. Explain what a web API is, why applications need one, and describe the client–server request/response model as a contract between systems.

2. Define REST as an architectural style, name its six constraints, and explain what each constraint buys you (and what ignoring it costs).

3. Model a domain as resources: design URIs for collections and items, and refactor an RPC-style API into a resource-oriented one.

4. Choose HTTP methods correctly using the safety and idempotency properties, including the PUT-vs-PATCH-vs-POST decision, and map CRUD operations onto them.

5. Distinguish path parameters from query parameters, and decide which one a given piece of request data should be.

6. Select appropriate status codes for common situations and design consistent, machine-readable error bodies.

7. Build and run a FastAPI application with uvicorn, and use the automatically generated interactive documentation at /docs.

8. Declare path parameters, query parameters, and request bodies in FastAPI using Python type hints, and predict how FastAPI validates each one.

9. Define Pydantic models for requests and responses, and explain what happens when a client sends data that does not match the model.

10. Use dependency injection (Depends) to share resources such as a data store across endpoints, and explain when async def endpoints help.

11. Write automated tests for an API using TestClient and pytest.

12. Trace, end to end, how a REST design decision becomes a line of FastAPI code.

6.2 Motivation: Design the Contract, Then Build It🔗

6.3 Running Example: TerpTasks🔗

Throughout these notes we build one application, growing it as we introduce each concept: TerpTasks, a small service for tracking course assignments. A task looks like this:

{
  "id": 1,
  "title": "REST API assignment",
  "course": "CMSC389A",
  "due": "2026-09-21",
  "priority": "medium",
  "done": false
}

Clients of TerpTasks will be able to:

• list tasks, optionally filtered by course or completion status,

• fetch a single task by its id,

• create new tasks,

• update tasks (e.g., mark them done), and

• delete tasks.

TerpTasks is becoming a campus service: the CLI and web UI will both talk to a hosted API, and other student projects want to integrate. The intern (working without a design doc—tsk) shipped this first draft over the weekend:

It works—the demo ran fine. Every section of this lecture will take a bite out of it: first we’ll redesign it as a proper REST API, then implement that design in FastAPI. Keep a running list of its sins as we go; there are at least eight.

6.4 API Fundamentals🔗

A web API (Application Programming Interface) is a contract, exposed over HTTP, that specifies a set of endpoints (URLs), the methods that may be applied to them (GET, POST, PUT, DELETE, etc.), the shape of the data each accepts, and the shape of the data each returns.

In plain English: an API is a menu. It tells client programs exactly what they can order (GET /tasks — “give me the list of tasks”), what information they must provide (“to create a task, send me a title and a due date”), and what they will get back (“a JSON object with an id field”).

Intuition. A web server that serves an API is like a restaurant with a strict menu and a very literal-minded kitchen. If you order something on the menu in the correct format, you get a predictable dish. If you order something that isn’t on the menu, you don’t get a shrug—you get a precise error code telling you what went wrong (404: we don’t have that; 422: your order form was filled out incorrectly).

Common misconception. Students often conflate a web API with a website. A website returns HTML for humans to read; an API returns structured data (almost always JSON) for programs to consume. FastAPI can serve HTML, but its purpose is the latter.

6.5 HTTP Fundamentals🔗

REST APIs are built on top of HTTP (HyperText Transfer Protocol), the same protocol your browser uses to fetch web pages. An HTTP request consists of a method, a URL, some headers, and an optional body:

An HTTP response consists of a status code, headers, and a body:

For example, a client asking TerpTasks for all tasks:

might receive:

{
  "tasks": [
    {
      "id": 1,
      "title": "REST API assignment",
      "course": "CMSC389A",
      "done": false
    }
  ]
}

The methods have conventional meanings. Respecting these conventions is what makes your API predictable to other developers (and to AI coding assistants, which have internalized the conventions from millions of examples)—the next two sections work out exactly what those conventions are and why.

6.6 HTTP Methods and CRUD🔗

Most APIs are, underneath, doing one of four things to data: Create, Read, Update, Delete. HTTP gives each of these a conventional method:

Applied to TerpTasks’ /tasks resource:

Each HTTP method also carries two contractual properties. A method is safe if it must not change server state (pure read). A method is idempotent if doing it N times has the same effect as doing it once.

(*A JSON-merge PATCH like {"done": true} happens to be idempotent; PATCH in general doesn’t promise it.)

Intuition. Safety and idempotency aren’t etiquette—they are machine-readable retry policy. A proxy that times out may re-send an idempotent request automatically; a crawler assumes GETs are harmless; your own client can blindly retry PUT/DELETE but must never blindly retry POST. When you choose a method, you are signing those promises on behalf of your implementation.

Why is PUT idempotent but POST not? Trace it. PUT /tasks/42 {"title":"Study", "done":false} sent three times: the final state is identical after each—replace with this document converges. POST /tasks {"title":"Study"} sent three times: three tasks exist. Add one of these accumulates. That single distinction decides real outages: a flaky network plus a retrying client against a POST endpoint is the classic double-charge bug.

PUT vs PATCH, concretely. Start: {"title": "Study", "course": "CMSC389A", "done": false}.

• PATCH /tasks/42 with {"done": true} → title and course survive: {"title": "Study", "course": "CMSC389A", "done": true}.

• PUT /tasks/42 with {"done": true} → you asked to replace the resource with a document that has no title and no course. A strict server rejects it (422, missing fields); a lenient one nulls the other fields. Either way, PUT-with-a-fragment is the bug.

Misconception. “POST is for create, PUT is for update.” Close but off-axis. PUT is replace at a known URI—it can create (PUT /tasks/my-chosen-id) if the client names the resource. POST is ask the collection to make/do something—the server picks the URI and returns it in Location. The real axis is idempotency and who controls the URI, not create-vs-update. “Completing a task” is a good stress test of this rule: it feels like an action deserving its own endpoint (POST /tasks/42/complete), but ask what actually changes—one field of one resource. State change → represent it as state (done: true) and use the verb that means “change state” (PATCH).

6.7 REST Resource Design🔗

6.8 Path Parameters vs Query Parameters🔗

Every REST design eventually asks the same question: does this piece of information belong in the path or in the query string? Getting this right is what separates a clean API from an inconsistent one.

Path parameters identify which resource you mean:

Here 123 is not optional and not a filter—it names one specific task. Removing it changes which thing you’re talking about.

Query parameters modify how or how much of a request: filtering, searching, sorting, pagination.

GET /tasks?course=CMSC389A&done=false is appropriate here because we’re still asking for the tasks collection—just a filtered view of it. Nothing about “which resource” changed; only “how much of it” did.

Intuition. If removing the value changes which thing you are talking about, it is a path parameter; if it changes how or how much, it is a query parameter.

An alternative worth knowing. You could instead write:

This can make sense when the API models courses and their tasks as a strong resource relationship—every task genuinely belongs to exactly one course, and “a course’s tasks” is a first-class concept clients navigate to. Compare that to /tasks?course=CMSC389A, which treats course as one of several independent filters (alongside done, priority, ...) on a single flat collection. Neither is “more correct”—these are API design choices, not absolute REST rules. The nesting is worth it only when the ownership is real and you’ll always need it; when in doubt, prefer the flatter query-string version, since it composes with other filters without multiplying URL shapes.

6.9 HTTP Status Codes🔗

The status code is the machine-readable verdict of a request, in three families you’ll use constantly: 2xx success, 4xx the client is wrong, 5xx the server is wrong.

The ones you’ll actually use for TerpTasks (deliberately not every code HTTP defines):

Applied to TerpTasks: successfully retrieving tasks → 200; successfully creating a task → 201; a task that doesn’t exist → 404; invalid request data → the appropriate 4xx.

401 vs 403 vs 404, worked. Request: DELETE /tasks/42. No token → 401 (authenticate first). Valid token, but task 42 belongs to another user → policy choice: 403 admits the task exists; 404 hides it (GitHub does this for private repos—existence itself is information). Valid token, own task, already deleted → 404, and note that this makes DELETE idempotent but not oblivious: the second delete changes nothing (idempotent) yet honestly reports the resource is gone.

Intuition. The status code is for code; the body is for humans and logs. Clients branch on the number (surface 422 to the user, page someone on 500). An API that returns 200 {"error": "not found"}—the intern’s updateTask does exactly this—is lying to every piece of software in the chain: caches store the “success,” monitors see 100% uptime during a total outage, and clients must parse prose to learn they failed. A request that “fails” should still succeed at the HTTP level: a well-formed 404, not a crash and not a disguised 200.

Error bodies: be boringly consistent. Pick one shape and use it for every error:

{
  "error": {
    "code": "task_due_in_past",
    "message": "Field 'due' must be today or later.",
    "field": "due"
  }
}

A stable machine-readable code, a human message, and a pointer to the offending input. FastAPI’s automatic 422 for Pydantic failures, which you’ll meet shortly, follows this spirit—and automates the check you would otherwise have to write by hand.

6.10 REST API Design Exercise🔗

Before writing any Python, design the API. TerpTasks needs endpoints to:

• list all tasks,

• get one task,

• get incomplete tasks,

• get tasks for CMSC389A,

• create a task,

• update a task, and

• delete a task.

Sketch each endpoint—method, path, and any query parameters—before reading on. A design in the spirit of this lecture looks like:

Discussion questions. For each line above: why is {id} a path parameter but course and done query parameters? What would break if id were a query parameter instead (GET /tasks?id=42)? If you wanted to support “update just the done field,” would you add a query parameter to PUT, change the method to PATCH, or add a new endpoint—and which choice does HTTP Methods and CRUD recommend, and why?

6.11 REST API code example🔗

The smallest REST API that is still REST: read-only tasks, standard library only—no Flask, no FastAPI, no Pydantic, and zero third-party dependencies. Save it as server.py.

import json
import re
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import urlparse

tasks = [
    {"id": 1, "title": "Study for 389A", "due": "2026-07-10", "done": False},
    {"id": 2, "title": "Read Fielding's dissertation", "due": "2026-07-12", "done": False},
]

TASK_URI = re.compile(r"^/tasks/(\d+)$")


class TaskHandler(BaseHTTPRequestHandler):
    def _send_json(self, status, body):
        self.send_response(status)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(body).encode("utf-8"))

    def do_GET(self):
        path = urlparse(self.path).path
        if path == "/tasks":
            # Collection GET: an envelope, never a bare array.
            self._send_json(200, {"items": tasks, "total": len(tasks)})
            return
        match = TASK_URI.match(path)
        if match:
            task = next((t for t in tasks if t["id"] == int(match.group(1))), None)
            if task is not None:
                self._send_json(200, task)
                return
        # One error shape for the whole API (see lecture: be boringly consistent).
        self._send_json(404, {"error": {"code": "not_found", "message": "no such resource"}})


if __name__ == "__main__":
    HTTPServer(("", 8000), TaskHandler).serve_forever()

How to run.

python3 server.py &                        # :8000; fg + Ctrl-C to stop
curl http://localhost:8000/tasks           # 200, envelope with items + total
curl http://localhost:8000/tasks/1         # 200, a single task
curl http://localhost:8000/tasks/99        # 404, the one error shape

6.12 Transition from REST to FastAPI🔗

REST describes how we design and interact with an API. FastAPI is a Python framework that helps us implement that design.

Everything from here forward assumes the design work above is done—the resources are named, the verbs are chosen, the status codes are decided. FastAPI’s job is to turn that design into running code with as little ceremony as possible. This ordering matters pedagogically: if you learn FastAPI syntax before REST design, it is tempting to let the framework’s defaults be your design. Learn the design first, and FastAPI becomes a fast, faithful translator of decisions you already made deliberately.

You’ll meet this pattern constantly beyond this course: GitHub’s API (which your Claude Code agent calls through the gh CLI and MCP servers), Stripe, Canvas, campus data services. A large fraction of the “tools” an AI agent calls are thin wrappers over REST APIs exactly like the one you’re about to build—so designing a good REST API is also designing a good tool surface for AI agents.

6.13 FastAPI Introduction🔗

What FastAPI gives you, concretely: routing from decorators, automatic parsing and validation of path/query/body data from Python type hints, JSON serialization of your return values, and interactive documentation generated from the same type hints—all from writing the code you’d want to write anyway.

Install the framework and a server into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]"

Here is the smallest possible TerpTasks—a single file, main.py:

from fastapi import FastAPI

# The application object. Everything in your API hangs off of it.
app = FastAPI(title="TerpTasks")

@app.get("/")
def root():
    # Returning a dict => FastAPI serializes it to JSON for you.
    return {"message": "Hello CMSC389A"}

Run it with uvicorn, the server that actually listens on a network port and forwards requests to your app object:

uvicorn main:app --reload

The main:app syntax means “in module main, find the variable app.” The –reload flag restarts the server when you edit a file—use it in development only.

curl http://127.0.0.1:8000/

{"message": "Hello CMSC389A"}

A path operation is the association of an HTTP method and a path template with a Python function (the path operation function, or informally the endpoint). In FastAPI it is created with a decorator: @app.get("/"), @app.post("/tasks"), and so on.

In plain English: the decorator registers your function in a routing table. When a request arrives, FastAPI looks up (method, path) in the table and calls your function.

Intuition. Think of app as a switchboard operator with a binder. The decorators write entries into the binder; at runtime the operator just looks up who should take each call.

With the server running, open http://127.0.0.1:8000/docs to see FastAPI’s generated documentation—we’ll come back to it in Swagger UI and OpenAPI once there’s a real API to look at.

6.14 FastAPI Routes🔗

REST API Design Exercise’s design maps directly onto FastAPI decorators:

The pattern repeats throughout this lecture: REST design tells us what the endpoint should be; FastAPI gives us the Python syntax to implement it. Nothing about which method or path is a FastAPI decision—that was already settled in REST API Design Exercise.

6.15 Path Parameters in FastAPI🔗

TerpTasks needs “fetch task number 7.” The id varies per request, so it becomes a path parameter:

@app.get("/tasks/{task_id}")
def read_task(task_id: int):
    return {"task_id": task_id, "title": "(stub)"}

A path parameter is a variable segment of the path template, written in curly braces, bound to a function argument of the same name. The argument’s type hint determines parsing and validation.

In plain English: {task_id} is a blank in the URL. FastAPI fills in the blank with whatever the client put there, converted to the declared type.

The type hint is doing real work. Request /tasks/7 and your function receives the integer 7, not the string "7". Request /tasks/banana and your function is never called at all—FastAPI rejects the request:

curl http://127.0.0.1:8000/tasks/banana

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "task_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "banana"
    }
  ]
}

Intuition. In frameworks without typed parsing, everything arriving from the network is a string, and every endpoint begins with defensive boilerplate: convert, check, return an error. FastAPI inverts this: you declare what you expect, and only data meeting the expectation reaches your code.

6.16 Query Parameters in FastAPI🔗

Path Parameters vs Query Parameters’s GET /tasks?course=CMSC389A&done=false becomes:

@app.get("/tasks")
def list_tasks(course: str | None = None, done: bool | None = None):
    # `course` and `done` both come from the query string.
    # Defaults make them optional.
    return {"filters": {"course": course, "done": done}}

A query parameter is a key–value pair in the URL’s query string, bound to a function argument by name. A parameter with a default value is optional; one without a default is required, and FastAPI returns 422 if it is missing.

Intuition. Path parameters identify a resource (“task 7”); query parameters modify a request about resources (“...but only the unfinished ones from CMSC389A”).

Note the conversions: ?done=false arrives as the Python boolean False (FastAPI accepts true/false, 1/0, yes/no). Again, ill-typed input (?done=lots) never reaches your code.

Misconception. Students often expect ?done=false to arrive as the string "false"—which in Python is truthy! In frameworks without typed parsing this is a notorious bug (if request.args.get("done"): is true for both "true" and "false"). The type hint done: bool | None eliminates the entire bug class.

6.17 Request Bodies and Pydantic🔗

Creating a task requires the client to send structured data—a JSON body. This is where Pydantic enters.

A Pydantic model is a class inheriting from pydantic.BaseModel whose class-level type annotations define a data schema. Instantiating the model from external data triggers validation: each field is checked (and where sensible, converted) against its annotation, and a structured error is produced on failure.

What a client must send to create a TerpTasks task:

from datetime import date
from enum import Enum
from pydantic import BaseModel, Field

class Priority(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"

class TaskCreate(BaseModel):
    """What a client sends to create a task."""
    title: str = Field(min_length=1, max_length=120)
    course: str = Field(min_length=1, max_length=20)
    due: date | None = None              # optional; "YYYY-MM-DD" if present
    priority: Priority = Priority.medium # optional with a default

To accept it, declare a parameter of that type. A parameter whose type is a Pydantic model is read from the request body:

@app.post("/tasks", status_code=201)
def create_task(data: TaskCreate):
    # If we get here, `data` is guaranteed valid:
    # non-empty title, real date, priority in the enum.
    return {"created": data.title, "priority": data.priority}

In plain English: the model is a bouncer at the door. Your function never sees a task with an empty title, a malformed date, or a priority of "super-urgent".

A well-formed request:

curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Read ch. 3", "course": "CMSC389A", "due": "2026-09-21"}'

{"created": "Read ch. 3", "priority": "medium"}

Note the two conversions FastAPI performed silently: "2026-09-21" became a datetime.date, and the omitted priority took its default. Now a malformed one—empty title, bogus date:

curl -X POST http://127.0.0.1:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "", "course": "CMSC389A", "due": "someday"}'

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "title"],
      "msg": "String should have at least 1 character",
      "input": ""
    },
    {
      "type": "date_from_datetime_parsing",
      "loc": ["body", "due"],
      "msg": "Input should be a valid date or datetime, invalid character in year",
      "input": "someday"
    }
  ]
}

The response is a 422 listing every problem with a machine-readable location (loc)—all without a single if statement in your code.

6.18 Responses: Models, Status Codes, and Errors🔗

class Task(TaskCreate):
    """A stored task: everything the client sent, plus server fields."""
    id: int
    done: bool = False

@app.post("/tasks", response_model=Task, status_code=201)
def create_task(data: TaskCreate):
    task = store.add(data)   # store assigns the id (next section)
    return task

from fastapi import HTTPException

@app.get("/tasks/{task_id}", response_model=Task)
def read_task(task_id: int):
    task = store.get(task_id)
    if task is None:
        raise HTTPException(status_code=404,
                            detail=f"No task with id {task_id}")
    return task

curl -i http://127.0.0.1:8000/tasks/999

6.19 Swagger UI and OpenAPI🔗

FastAPI generates a machine-readable description of your entire API—every path, method, parameter, and schema—called the OpenAPI specification, available at /openapi.json. Swagger UI, served at /docs, renders that specification as an interactive page: every endpoint, its parameters, its schemas, and a button to execute requests right from the browser. A second rendering lives at /redoc.

This is not a gimmick. The docs are generated from your type hints and Pydantic models, so they cannot drift out of date the way hand-written docs do. Open /docs for TerpTasks and try GET /tasks, GET /tasks/{task_id}, POST /tasks, PATCH /tasks/{task_id}, and DELETE /tasks/{task_id} directly from the page.

Common misconception. Swagger UI is not the REST API itself—it is a tool for documenting and interacting with an API that already exists. Deleting /docs would not change what your API does; it would only remove a convenient way to explore it. In team projects, /docs is how your front-end teammates learn your API—and the OpenAPI spec is excellent context to paste into an LLM when asking it to write a client for your service.

6.20 Dependency Injection with Depends🔗

So far “the store” has been hand-waved. The obvious move is a global variable, and for a toy that works. But globals make testing painful (tests share state) and hide what each endpoint needs. FastAPI’s answer is its dependency injection system.

A dependency is a callable that FastAPI invokes before your endpoint, whose return value is passed in as an argument. You declare it with Depends(callable) as the parameter’s default value.

from fastapi import Depends

# storage.py -----------------------------------------------------------
class TaskStore:
    """An in-memory 'database': a dict of id -> Task."""
    def __init__(self):
        self._tasks: dict[int, Task] = {}
        self._next_id = 1

    def add(self, data: TaskCreate) -> Task:
        task = Task(id=self._next_id, **data.model_dump())
        self._tasks[task.id] = task
        self._next_id += 1
        return task

    def get(self, task_id: int) -> Task | None:
        return self._tasks.get(task_id)

store = TaskStore()          # one shared instance for the whole app

def get_store() -> TaskStore:
    return store

# main.py --------------------------------------------------------------
@app.get("/tasks/{task_id}", response_model=Task)
def read_task(task_id: int, store: TaskStore = Depends(get_store)):
    task = store.get(task_id)
    if task is None:
        raise HTTPException(status_code=404,
                            detail=f"No task with id {task_id}")
    return task

In plain English: instead of the endpoint reaching out for the store, the store is handed to the endpoint. The endpoint declares what it needs; the framework supplies it.

Intuition. Think of a chef who lists ingredients rather than shopping mid-recipe. Because the ingredients are listed, you can substitute them: in tests, we will hand the endpoint a fresh store instead of the shared one—without modifying the endpoint at all. That substitution (app.dependency_overrides) is the payoff, and we use it in Testing FastAPI Applications.

6.21 Build a Complete CRUD API🔗

Time to assemble every piece into the full TerpTasks API, built up incrementally rather than all at once.

"""Pydantic schemas for TerpTasks.

Three models, one per direction of data flow:
  TaskCreate -- what clients send to create a task
  TaskUpdate -- what clients send to modify one (all fields optional)
  Task       -- what the server stores and returns
"""
from datetime import date
from enum import Enum

from pydantic import BaseModel, Field


class Priority(str, Enum):
    low = "low"
    medium = "medium"
    high = "high"


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=120,
                       examples=["Finish FastAPI reading"])
    course: str = Field(min_length=1, max_length=20, examples=["CMSC389A"])
    due: date | None = None
    priority: Priority = Priority.medium


class TaskUpdate(BaseModel):
    """All fields optional: clients send only what they want to change."""
    title: str | None = Field(default=None, min_length=1, max_length=120)
    course: str | None = Field(default=None, min_length=1, max_length=20)
    due: date | None = None
    priority: Priority | None = None
    done: bool | None = None


class Task(TaskCreate):
    """Server-side representation: client fields plus server-owned fields."""
    id: int
    done: bool = False

from .models import Task, TaskCreate, TaskUpdate


class TaskStore:
    def __init__(self) -> None:
        self._tasks: dict[int, Task] = {}
        self._next_id = 1

    def add(self, data: TaskCreate) -> Task:
        task = Task(id=self._next_id, **data.model_dump())
        self._tasks[task.id] = task
        self._next_id += 1
        return task

    def get(self, task_id: int) -> Task | None:
        return self._tasks.get(task_id)

    def list(self, course: str | None = None,
             done: bool | None = None) -> list[Task]:
        tasks = list(self._tasks.values())
        if course is not None:
            tasks = [t for t in tasks if t.course == course]
        if done is not None:
            tasks = [t for t in tasks if t.done == done]
        return tasks

    def update(self, task_id: int, changes: TaskUpdate) -> Task | None:
        task = self._tasks.get(task_id)
        if task is None:
            return None
        # Only apply fields the client actually sent.
        updated = task.model_copy(
            update=changes.model_dump(exclude_unset=True))
        self._tasks[task_id] = updated
        return updated

    def delete(self, task_id: int) -> bool:
        return self._tasks.pop(task_id, None) is not None


store = TaskStore()


def get_store() -> TaskStore:
    """Dependency: hands endpoints the shared store (tests override this)."""
    return store

"""TerpTasks: a task-tracking API for course assignments."""
from fastapi import Depends, FastAPI, HTTPException

from .models import Task, TaskCreate, TaskUpdate
from .storage import TaskStore, get_store

app = FastAPI(
    title="TerpTasks",
    description="Track assignments across your courses.",
    version="1.0.0",
)


@app.get("/")
def read_root():
    return {"message": "Welcome to TerpTasks! See /docs for the API."}


@app.get("/tasks", response_model=list[Task])
def list_tasks(course: str | None = None, done: bool | None = None,
               store: TaskStore = Depends(get_store)):
    return store.list(course=course, done=done)


@app.post("/tasks", response_model=Task, status_code=201)
def create_task(data: TaskCreate,
                store: TaskStore = Depends(get_store)):
    return store.add(data)


@app.get("/tasks/{task_id}", response_model=Task)
def read_task(task_id: int, store: TaskStore = Depends(get_store)):
    task = store.get(task_id)
    if task is None:
        raise HTTPException(404, detail=f"No task with id {task_id}")
    return task


@app.patch("/tasks/{task_id}", response_model=Task)
def update_task(task_id: int, changes: TaskUpdate,
                store: TaskStore = Depends(get_store)):
    task = store.update(task_id, changes)
    if task is None:
        raise HTTPException(404, detail=f"No task with id {task_id}")
    return task


@app.delete("/tasks/{task_id}", status_code=204)
def delete_task(task_id: int, store: TaskStore = Depends(get_store)):
    if not store.delete(task_id):
        raise HTTPException(404, detail=f"No task with id {task_id}")

git clone <your-repo-url> terptasks && cd terptasks
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

uvicorn app.main:app --reload    # serve at http://127.0.0.1:8000
pytest -q                        # run the test suite

curl -s -X POST localhost:8000/tasks -H 'Content-Type: application/json' \
  -d '{"title":"FastAPI notes","course":"CMSC389A","priority":"high"}'
# => {"title":"FastAPI notes","course":"CMSC389A","due":null,
#     "priority":"high","id":1,"done":false}

curl -s -X PATCH localhost:8000/tasks/1 -H 'Content-Type: application/json' \
  -d '{"done": true}'
# => {... "done":true}   (only `done` changed)

curl -s 'localhost:8000/tasks?course=CMSC389A&done=true'
# => [{...task 1...}]

curl -s -X DELETE localhost:8000/tasks/1 -i | head -1
# => HTTP/1.1 204 No Content

6.22 async def: When It Matters🔗

You will see both of these in the wild, and FastAPI accepts both:

@app.get("/sync")
def handler_a():
    ...

@app.get("/async")
async def handler_b():
    ...

An async def endpoint runs as a coroutine on the server’s event loop; it may await other coroutines, yielding control while waiting. A plain def endpoint is run in a thread pool so it cannot block the loop.

Intuition. An async server is a barista who starts your espresso shot and, while the machine runs, takes the next order. await marks the moments the barista is free to do other work. A synchronous handler is a barista who stares at the machine until the shot finishes.

The rule of thumb:

• If your handler calls async-capable I/O (an async HTTP client like httpx calling an LLM API, an async database driver), use async def and await—one process can then juggle hundreds of in-flight requests.

• If your handler only does quick in-memory work (like TerpTasks), or uses blocking libraries (requests, time.sleep, classic database drivers), use plain def.

The misconception that bites hardest: writing async def and then calling blocking code inside it. That blocks the entire event loop—every other request in the process stalls. async def is not a “go faster” keyword; it is a promise that everything slow inside is awaited. When in doubt, plain def is the safe default, and it is what TerpTasks uses.

A realistic preview of where you will want async later in the course—proxying an LLM:

import httpx

@app.post("/summarize")
async def summarize(doc: DocumentIn):
    async with httpx.AsyncClient() as client:
        r = await client.post(LLM_API_URL, json=make_prompt(doc))
    return {"summary": r.json()["content"]}

While one request awaits the model (often seconds!), the server keeps handling others.

6.23 Testing FastAPI Applications🔗

An untested API is a rumor. FastAPI ships a TestClient that calls your app in-process—no server, no network, no uvicorn—so tests are fast and deterministic.

from fastapi.testclient import TestClient
from app.main import app
from app.storage import TaskStore, get_store

import pytest

@pytest.fixture()
def client():
    # Hand every test a FRESH store via dependency override,
    # so tests cannot leak state into each other.
    fresh = TaskStore()
    app.dependency_overrides[get_store] = lambda: fresh
    yield TestClient(app)
    app.dependency_overrides.clear()

def test_create_then_fetch(client):
    r = client.post("/tasks", json={"title": "Study", "course": "CMSC389A"})
    assert r.status_code == 201
    task_id = r.json()["id"]

    r = client.get(f"/tasks/{task_id}")
    assert r.status_code == 200
    assert r.json()["title"] == "Study"
    assert r.json()["done"] is False

def test_missing_task_is_404(client):
    assert client.get("/tasks/999").status_code == 404

def test_validation_rejects_empty_title(client):
    r = client.post("/tasks", json={"title": "", "course": "CMSC389A"})
    assert r.status_code == 422

Walk through test_create_then_fetch step by step:

1. The fixture builds a brand-new TaskStore and tells the app: “whenever an endpoint asks for get_store, give it this one instead.” This is dependency injection (Dependency Injection with Depends) paying rent.

2. client.post(..., json=...) serializes the dict, sends it through the full FastAPI stack—routing, validation, serialization—and returns a response object. This is an integration test of the real request path.

3. We assert on the status code first (the contract from HTTP Status Codes), then on the body. Note we read the id from the create response and use it in the fetch—tests should not assume ids start at 1.

pytest -q

Practical implication for this course. When you ask an AI assistant to extend your API, these tests are your verification harness. A green test suite after an AI-written change is evidence; “it looks right” is not. Get in the habit of asking for the tests first, reviewing them, and only then asking for the implementation.

6.24 Connecting REST Concepts to FastAPI🔗

A review of the entire pipeline, concept by concept:

This table is the whole lecture compressed: every row on the left was a design decision you know how to make; every row on the right is the one line of FastAPI that carries it out.

6.25 Practice Exercises🔗

6.26 Final Review🔗

• What is an API?

• What makes an API RESTful?

• What is the difference between a resource and an action?

• When should you use a path parameter?

• When should you use a query parameter?

• What is the difference between PUT and POST?

• When should an API return 201?

• What does a Pydantic model do?

• What does @app.get() do?

• What is OpenAPI?

• What is Swagger UI?

• What does Depends buy you that a global variable does not?

• When does async def actually help, and when does it hurt?

• Why test with TestClient instead of manually curling a running server?

• How does FastAPI implement REST concepts?

6.27 Summary🔗