python-fastapi

FastAPI Implementation Patterns

Use this skill for idiomatic FastAPI development. FastAPI's design rewards explicit typing, proper dependency injection, and clean separation of routing from business logic.

Delivery Workflow

FastAPI progress:
- [ ] Step 1: Discover project router structure, middleware, and DI conventions
- [ ] Step 2: Define request/response models and route contracts
- [ ] Step 3: Implement route handlers — thin, delegating to services
- [ ] Step 4: Wire dependencies, auth, and middleware correctly
- [ ] Step 5: Verify OpenAPI docs, error responses, and integration tests

Route Design

• Keep route handlers thin: parse input, call a service, return a response. No business logic in handlers.
• Use APIRouter to group routes by domain; mount routers in main.py with a clear prefix.
• Define explicit response models with response_model= on every route — never return raw dicts.
• Use status_code= explicitly; do not accept FastAPI's implicit 200 for non-GET routes.
• Annotate path and query parameters with types and Field(...) for validation and documentation.

from fastapi import APIRouter, status
from app.schemas.document import DocumentResponse, CreateDocumentRequest
from app.services.document_service import DocumentService

router = APIRouter(prefix="/documents", tags=["documents"])

@router.post(
    "/",
    response_model=DocumentResponse,
    status_code=status.HTTP_201_CREATED,
)
async def create_document(
    payload: CreateDocumentRequest,
    service: DocumentService = Depends(get_document_service),
) -> DocumentResponse:
    return await service.create(payload)

Request and Response Models

• Use Pydantic v2 BaseModel for all request and response schemas.
• Keep request models (input validation) separate from response models (output shaping) and domain models (business logic).
• Use model_config = {"from_attributes": True} on response models that map from ORM objects.
• Use Field(...) for documentation, validation constraints, and aliases.
• Never expose internal domain model fields in response schemas — map explicitly.