Your First FastAPI Vertical Slice

A FastAPI application connects an HTTP operation to typed Python behavior and automatically publishes an OpenAPI contract. Your first vertical slice will accept a validated ticket, return a response, expose interactive documentation, and run through an automated test. Its in-memory storage is intentionally temporary and not production persistence.

What will you be able to do?

create and run a FastAPI application;
define health, create, and read operations;
inspect OpenAPI rather than trusting assumptions;
test through HTTP using FastAPI's test client.

How do you build the smallest useful service?

Create src/supportdesk_ai/main.py:

python

from uuid import UUID, uuid4

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

app = FastAPI(title="SupportDesk AI", version="0.1.0")
tickets: dict[UUID, "TicketView"] = {}


class TicketCreate(BaseModel):
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
    subject: str = Field(min_length=1, max_length=120)
    body: str = Field(min_length=1, max_length=10_000)


class TicketView(TicketCreate):
    id: UUID
    status: str


@app.get("/healthz", tags=["operations"])
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.post("/v1/tickets", response_model=TicketView, status_code=status.HTTP_201_CREATED)
def create_ticket(command: TicketCreate) -> TicketView:
    ticket = TicketView(id=uuid4(), status="open", **command.model_dump())
    tickets[ticket.id] = ticket
    return ticket


@app.get("/v1/tickets/{ticket_id}", response_model=TicketView)
def get_ticket(ticket_id: UUID) -> TicketView:
    ticket = tickets.get(ticket_id)
    if ticket is None:
        raise HTTPException(status_code=404, detail="ticket not found")
    return ticket

Run and verify:

bash

uv run uvicorn supportdesk_ai.main:app --reload
curl -i http://127.0.0.1:8000/healthz
curl -s http://127.0.0.1:8000/openapi.json

Open /docs, create a ticket, copy its ID, and read it back. Restart the server and observe that the ticket disappears; this proves storage is process memory.

How do you test through the boundary?

python

from fastapi.testclient import TestClient
from supportdesk_ai.main import app

client = TestClient(app)


def test_create_ticket() -> None:
    response = client.post(
        "/v1/tickets",
        json={"subject": "Cannot sign in", "body": "Reset expired"},
    )
    assert response.status_code == 201
    assert response.json()["status"] == "open"

Why does this matter in AI-native systems?

OpenAPI can describe deterministic API operations, but it must not automatically expose every route as an AI tool. Tool schemas require narrower permissions, descriptions, limits, approval policy, and server-bound identity. The same Pydantic rigor will later validate model outputs.

Common mistakes

--reload in production spawns development behavior; use it locally only.
Global dictionaries lose data and diverge across workers.
Returning raw exception text can leak internals.
Interactive docs are useful but may require authentication or disabling in sensitive production contexts.
Import-time network calls make startup and tests fragile.

AI Pair-Programmer Prompt

text

Review this first FastAPI slice for request/response contract accuracy. Inspect
status codes, validation, OpenAPI output, process-local state, negative tests, and
what must change before production. Keep the example small; do not add a framework.

Exercise

Add GET /v1/tickets with a maximum limit of 100 and a deterministic order. Test valid creation, invalid empty input, missing ID, and bounded listing.

Acceptance criteria: OpenAPI documents constraints, all tests pass, and restart behavior is recorded honestly.

Knowledge check

What generates the OpenAPI request schema?
Why does data vanish on restart?
Is every API operation a safe AI tool?

Answers

FastAPI uses the type annotations and Pydantic models.
It exists only in a process-local dictionary.
No; tool exposure needs separate permission and safety design.

Completion checklist

Health, create, read, and tests work.
I inspected OpenAPI.
I can explain why this storage is temporary.

Primary references

Your First FastAPI Vertical Slice

How do you build the smallest useful service?

Create src/supportdesk_ai/main.py:

python

from uuid import UUID, uuid4

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

app = FastAPI(title="SupportDesk AI", version="0.1.0")
tickets: dict[UUID, "TicketView"] = {}


class TicketCreate(BaseModel):
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
    subject: str = Field(min_length=1, max_length=120)
    body: str = Field(min_length=1, max_length=10_000)


class TicketView(TicketCreate):
    id: UUID
    status: str


@app.get("/healthz", tags=["operations"])
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.post("/v1/tickets", response_model=TicketView, status_code=status.HTTP_201_CREATED)
def create_ticket(command: TicketCreate) -> TicketView:
    ticket = TicketView(id=uuid4(), status="open", **command.model_dump())
    tickets[ticket.id] = ticket
    return ticket


@app.get("/v1/tickets/{ticket_id}", response_model=TicketView)
def get_ticket(ticket_id: UUID) -> TicketView:
    ticket = tickets.get(ticket_id)
    if ticket is None:
        raise HTTPException(status_code=404, detail="ticket not found")
    return ticket

Run and verify:

bash

uv run uvicorn supportdesk_ai.main:app --reload
curl -i http://127.0.0.1:8000/healthz
curl -s http://127.0.0.1:8000/openapi.json

Open /docs, create a ticket, copy its ID, and read it back. Restart the server and observe that the ticket disappears; this proves storage is process memory.

How do you test through the boundary?

python

from fastapi.testclient import TestClient
from supportdesk_ai.main import app

client = TestClient(app)


def test_create_ticket() -> None:
    response = client.post(
        "/v1/tickets",
        json={"subject": "Cannot sign in", "body": "Reset expired"},
    )
    assert response.status_code == 201
    assert response.json()["status"] == "open"

Common mistakes

--reload in production spawns development behavior; use it locally only.

Global dictionaries lose data and diverge across workers.

Returning raw exception text can leak internals.

Interactive docs are useful but may require authentication or disabling in sensitive production contexts.

Import-time network calls make startup and tests fragile.

AI Pair-Programmer Prompt

text

Review this first FastAPI slice for request/response contract accuracy. Inspect
status codes, validation, OpenAPI output, process-local state, negative tests, and
what must change before production. Keep the example small; do not add a framework.