FastAPI & Pydantic v2 Boilerplate Cheatsheet: The Complete Reference

FastAPI is a modern, high-performance web framework for building APIs with Python 3.8+ based on standard Python type hints. By leveraging Pydantic v2 for data validation and Starlette for asynchronous execution routing, it achieves speeds competitive with Go and Node.js.

This reference sheet covers base setup, Pydantic v2 validation models, router architecture, dependency injection, async database integrations, and custom exception handling.

- **Base Server**: Launch applications with clean lifecycle event handlers (`lifespan`) and async routes. - **Pydantic v2**: Declare type-safe validation models using fields, aliases, and custom decorators (`@field_validator`). - **Dependency Injection**: Streamline access to resources like database sessions and authentication layers via `Depends`. - **Async DB Integration**: Combine async operations with SQLAlchemy or Tortoise ORM for high concurrent request handling. - **Error Handlers**: Intercept and standardize API validation error outputs cleanly.

Before diving into this cheatsheet, check out my previous deep-dive on PyTorch & CUDA ML Operations Cheatsheet: The Complete Reference to see how we structured these patterns in practice.

FastAPI Server Initialization

FastAPI uses standard ASGI web servers like Uvicorn or Hypercorn for asynchronous execution. Below is a base server initialization using the modern lifespan pattern to manage startup and shutdown events.

from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Startup: Initialize database connections, load ML models, warm caches
    print("FastAPI server starting up...")
    yield
    # Shutdown: Clean up resources, close sockets, flush logs
    print("FastAPI server shutting down...")

# Create the FastAPI instance
app = FastAPI(
    title="MeshWorld API Service",
    description="High-performance backend API boilerplate",
    version="1.0.0",
    lifespan=lifespan
)

@app.get("/health", tags=["system"])
async def health_check():
    return {"status": "operational", "code": 200}

Pydantic v2 Data Validation

Pydantic v2 has been rewritten in Rust, bringing immense speed gains to validation pipelines. Use it to declare request bodies, response shapes, and query configurations.

from typing import Optional
from pydantic import BaseModel, Field, EmailStr, field_validator

# 1. Base Registration Request Model
class UserCreateRequest(BaseModel):
    username: str = Field(..., min_length=3, max_length=20, description="Unique display name")
    email: EmailStr = Field(..., description="Primary contact address")
    password: str = Field(..., min_length=8, description="Strong passphrase")
    age: Optional[int] = Field(None, ge=18, le=120, description="Age must be 18 or older")

    # 2. Custom Field Validator
    @field_validator('username')
    @classmethod
    def validate_alphanumeric_username(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError('Username must be strictly alphanumeric')
        return v

# 3. Secure Response Model (Prevents password leaks)
class UserResponse(BaseModel):
    id: int
    username: str
    email: EmailStr
    is_active: bool = True

    # Pydantic v2 config to enable extraction from ORM schemas
    model_config = {
        "from_attributes": True
    }

Modular Router Architecture

Organize your application features into separate modules using the APIRouter class.

from fastapi import APIRouter, HTTPException, status

user_router = APIRouter(prefix="/users", tags=["users"])

# Local database store simulation
USERS_DB = []

@user_router.post(
    "/", 
    response_model=UserResponse, 
    status_code=status.HTTP_201_CREATED
)
async def register_user(payload: UserCreateRequest):
    # Verify username uniqueness
    if any(u['username'] == payload.username for u in USERS_DB):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, 
            detail="Username already registered"
        )
    
    new_user = {
        "id": len(USERS_DB) + 1,
        "username": payload.username,
        "email": payload.email,
        "is_active": True
    }
    USERS_DB.append(new_user)
    return new_user

# Mount the router to the main application
app.include_router(user_router)

Dependency Injection Engine

Dependency Injection in FastAPI allows you to inject functions into endpoint signatures, sharing logic like database sessions, authentication, and permission gates.

from fastapi import Depends, Header

# 1. Dependency: Extract and verify authorization token
async def verify_auth_token(x_api_key: str = Header(..., description="API key token")):
    if x_api_key != "secret-meshworld-key":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED, 
            detail="Invalid or missing API Key"
        )
    return x_api_key

# 2. Consume the dependency in a protected route
@user_router.get("/me", response_model=UserResponse)
async def get_current_user(api_key: str = Depends(verify_auth_token)):
    # This route is only executed if verify_auth_token completes successfully
    return {
        "id": 1,
        "username": "admin_user",
        "email": "admin@meshworld.in",
        "is_active": True
    }

Async Database Integrations (SQLAlchemy)

Integrate FastAPI with asynchronous SQLAlchemy models to achieve parallel, non-blocking I/O database operations.

from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession

DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/dbname"

# Create the asynchronous database engine
engine = create_async_engine(DATABASE_URL, echo=False, future=True)

# Create an async session factory
async_session_factory = async_sessionmaker(
    bind=engine, 
    class_=AsyncSession, 
    expire_on_commit=False
)

# Dependency to yield database sessions per request
async def get_db_session() -> AsyncSession:
    async with async_session_factory() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise
        finally:
            await session.close()

Intercepting Validation Exceptions

When input validation fails, FastAPI raises a RequestValidationError. You can override the default handler to structure validation errors matching your organization’s API response standard.

from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc: RequestValidationError):
    # Formulate a structured error response
    error_details = []
    for err in exc.errors():
        error_details.append({
            "field": ".".join(map(str, err["loc"][1:])),
            "issue": err["msg"],
            "type": err["type"]
        })
        
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "message": "Input validation failed",
            "errors": error_details
        }
    )