FastAPI Development Guide

Build modern, fast Python APIs from hello world to production-ready applications.

Before Implementation

Gather context to ensure successful implementation:

Clarifications

Required (ask if not clear)

1. Project type? Simple API / Production application / Microservice
2. Database? PostgreSQL / SQLite / None / Other
3. Authentication needed? JWT / API Key / OAuth2 / None

Optional (ask if relevant)

4. Deployment target? Docker / Cloud (Railway/Render/Fly.io) / Local only
5. Testing approach? TDD / Post-implementation / None

Official Documentation

Version Note: This skill follows FastAPI 0.100+ and Pydantic v2 patterns. For older versions, check official migration guides.

Quick Start

uv init my-api && cd my-api
uv add "fastapi[standard]"

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

uv run fastapi dev main.py

Access at http://127.0.0.1:8000 | Docs at /docs | ReDoc at /redoc

Project Structure

Simple projects:

project/
├── main.py
├── requirements.txt
└── .env

Production projects:

project/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI app instance
│   ├── config.py         # Settings/configuration
│   ├── dependencies.py   # Shared dependencies
│   ├── models/           # SQLAlchemy models
│   ├── schemas/          # Pydantic schemas
│   ├── routers/          # API route modules
│   ├── services/         # Business logic
│   └── utils/            # Helper functions
├── tests/
├── alembic/              # DB migrations
├── requirements.txt
├── .env
└── Dockerfile

Core Concepts

Path Operations

@app.get("/items/{item_id}")      # Read
@app.post("/items/")               # Create
@app.put("/items/{item_id}")       # Update (full)
@app.patch("/items/{item_id}")     # Update (partial)
@app.delete("/items/{item_id}")    # Delete

Parameters

from fastapi import FastAPI, Query, Path, Body

@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(..., ge=1),              # Path param, required, >= 1
    q: str | None = Query(None, max_length=50),  # Query param, optional
    skip: int = Query(0, ge=0),                  # Query param with default
):
    return {"item_id": item_id, "q": q, "skip": skip}

Request/Response Models

from pydantic import BaseModel, Field, EmailStr

class UserCreate(BaseModel):
    email: EmailStr
    password: str = Field(..., min_length=8)
    name: str

class UserResponse(BaseModel):
    id: int
    email: EmailStr
    name: str

    model_config = {"from_attributes": True}

@app.post("/users/", response_model=UserResponse)
async def create_user(user: UserCreate):
    # Create user in DB...
    return user

Dependency Injection

from fastapi import Depends

async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = decode_token(token)
    if not user:
        raise HTTPException(401, "Invalid token")
    return user

@app.get("/users/me")
async def read_users_me(user: User = Depends(get_current_user)):
    return user

Error Handling

from fastapi import HTTPException
from fastapi.responses import JSONResponse

# Simple exception
raise HTTPException(status_code=404, detail="Item not found")

# Custom exception handler
class ItemNotFound(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFound)
async def item_not_found_handler(request, exc):
    return JSONResponse(
        status_code=404,
        content={"message": f"Item {exc.item_id} not found"}
    )

Workflow Selection

Starting a new project? → See references/basics.md

Need data validation/schemas? → See references/models-validation.md

Connecting a database? → See references/database.md

Adding authentication? → See references/authentication.md

Need WebSockets, background tasks, or middleware? → See references/advanced.md

Writing tests? → See references/testing.md (includes TDD workflow)

Deploying to production? → See references/deployment.md

Searching Large References

For specific patterns in reference files, use grep:

# Authentication patterns
grep -n "JWT\|OAuth2\|token\|password" references/authentication.md

# Database patterns
grep -n "async\|session\|CRUD\|relationship" references/database.md

# Testing patterns
grep -n "fixture\|mock\|async_client" references/testing.md

# Deployment patterns
grep -n "Docker\|gunicorn\|nginx" references/deployment.md

Common Patterns

Router Organization

# app/routers/users.py
from fastapi import APIRouter

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

@router.get("/")
async def list_users():
    return []

@router.get("/{user_id}")
async def get_user(user_id: int):
    return {"id": user_id}

# app/main.py
from fastapi import FastAPI
from app.routers import users, items

app = FastAPI()
app.include_router(users.router)
app.include_router(items.router)

Background Tasks

from fastapi import BackgroundTasks

def send_email(email: str, message: str):
    # Send email logic...
    pass

@app.post("/send-notification/")
async def send_notification(
    email: str,
    background_tasks: BackgroundTasks
):
    background_tasks.add_task(send_email, email, "Welcome!")
    return {"message": "Notification sent in background"}

File Upload

from fastapi import UploadFile, File

@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type
    }

CORS

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Essential Dependencies

# Core
uv add "fastapi[standard]"

# Database
uv add sqlalchemy asyncpg alembic  # PostgreSQL async
uv add sqlalchemy aiosqlite        # SQLite async

# Authentication
uv add "python-jose[cryptography]" "passlib[bcrypt]"

# Validation
uv add "pydantic[email]"

# Testing
uv add pytest pytest-asyncio httpx --dev

Common Mistakes

Quick Reference

Before Delivery Checklist

Code Quality

• All endpoints have appropriate HTTP status codes (201 for create, 204 for delete)
• Sensitive data filtered via response_model (no passwords in responses)
• Input validation using Pydantic models
• Error handling with proper HTTPException messages

Security

• SECRET_KEY from environment variable
• CORS configured with specific origins (not *)
• Authentication on protected routes
• No hardcoded credentials

Testing

• Tests written for all endpoints
• Error cases covered (404, 401, 422)
• Tests pass: uv run pytest

Documentation

• OpenAPI docs accessible at /docs
• Endpoints have descriptive tags and summaries