fastapi
FastAPI and Pydantic conventions for API work: `Annotated` parameters and dependencies, return types and response models, router-level parameters, async versus sync path operations, JSON Lines / SSE /
SKILL.mdskills/dev/parts/fastapi/SKILL.md
GitHubFastAPI
Part of the
devrouter. The body below is the core; details live inreferences/and are read by topic.
Choosing a reference
| Need | Read |
|---|---|
Models, validation, no RootModel, no ... |
references/pydantic.md |
Response shapes, filtering, response_model |
references/responses.md |
| Routing, prefixes, tags, shared dependencies | references/path-operations.md |
yield dependencies, scopes, class dependencies |
references/dependencies.md |
| JSON Lines, SSE, byte streaming | references/streaming.md |
| Frontend serving, OpenTelemetry, uv/Ruff/ty, Asyncer/SQLModel/HTTPX | references/frontend-and-telemetry.md, references/other-tools.md |
The fastapi CLI
fastapi dev # local, reload
fastapi run # production
Prefer the entrypoint in pyproject.toml; pass a path only when that is not possible:
[tool.fastapi]
entrypoint = "my_app.main:app"
Annotated for parameters and dependencies
Always prefer Annotated; it keeps signatures reusable and typed.
from typing import Annotated
from fastapi import Depends, FastAPI, Path, Query
app = FastAPI()
def get_current_user():
return {"username": "johndoe"}
CurrentUserDep = Annotated[dict, Depends(get_current_user)]
@app.get("/items/{item_id}")
async def read_item(
item_id: Annotated[int, Path(ge=1, description="The item ID")],
q: Annotated[str | None, Query(max_length=50)] = None,
current_user: CurrentUserDep = None,
):
return {"message": "Hello World"}
No ... for required fields
Do not use ... as a default for required parameters or model fields; a missing
default already means required.
class Item(BaseModel):
name: str
description: str | None = None
price: float = Field(gt=0)
Return types and response models
Declare a return type when possible: FastAPI validates, filters, documents and serializes from it, and Pydantic does the serialization in Rust.
@app.get("/items/me")
async def get_item() -> Item:
return Item(name="Plumbus", description="All-purpose home device")
Use response_model only when the public schema differs from what the function
returns. Do not use ORJSONResponse / UJSONResponse — deprecated; the return
type covers the performance case.
Routers
Declare prefix, tags and shared dependencies on the APIRouter, not in
include_router().
router = APIRouter(prefix="/items", tags=["items"], dependencies=[Depends(get_current_user)])
@router.get("/")
async def list_items():
return []
app.include_router(router)
Dependencies
Use a dependency when the logic cannot live in Pydantic validation, needs an
external resource, needs cleanup via yield, or is shared across endpoints.
Apply shared ones at the router level.
Async versus sync
async def only when every call inside is genuinely awaitable and non-blocking.
When in doubt use def: FastAPI runs it in a threadpool, so it does not block the
loop. Blocking calls inside async functions work but destroy throughput; for
mixing the two, use Asyncer (references/other-tools.md).
Streaming
from collections.abc import AsyncIterable
from fastapi import FastAPI
from fastapi.sse import EventSourceResponse, ServerSentEvent
app = FastAPI()
@app.get("/events", response_class=EventSourceResponse)
async def stream_events() -> AsyncIterable[ServerSentEvent]:
yield ServerSentEvent(data={"status": "started"}, event="status", id="1")
Plain objects are serialized as SSE data: fields; ServerSentEvent gives full
control, raw_data takes pre-formatted strings. JSON Lines and byte streaming:
references/streaming.md.
No RootModel
Use Annotated with validation utilities instead of a wrapper model:
@app.post("/items/")
async def create_items(items: Annotated[list[int], Field(min_length=1), Body()]):
return items
One HTTP operation per function
One function per method keeps concerns separate and the OpenAPI document honest. Do not branch on the verb inside a single handler.