FastAPI Development Guide

Build REST APIs with FastAPI - from Hello World to production.

Quick Start

Minimal App

from fastapi import FastAPI
app = FastAPI()

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

Run: fastapi dev main.py → Visit http://127.0.0.1:8000/docs

New Project Setup

Copy starter template from assets/starter-project/ or:

pip install "fastapi[standard]"

Core Concepts

Reference Files

Load these based on the task at hand:

Project Structure (Professional)

project/
├── main.py              # App entry point
├── app/
│   ├── __init__.py
│   ├── config.py        # Settings (pydantic-settings)
│   ├── database.py      # DB connection, session
│   ├── models/          # SQLAlchemy models
│   ├── schemas/         # Pydantic schemas
│   ├── api/
│   │   ├── v1/
│   │   │   ├── endpoints/
│   │   │   └── router.py
│   │   └── deps.py      # Common dependencies
│   ├── services/        # Business logic
│   └── repositories/    # Data access layer
├── tests/
├── alembic/             # Migrations
├── Dockerfile
└── requirements.txt

Common Patterns

CRUD Endpoint

@router.post("/", response_model=ItemOut, status_code=201)
def create(item: ItemCreate, db: DBDep, user: UserDep):
    return service.create_item(db, item, user.id)

@router.get("/{id}", response_model=ItemOut)
def read(id: int, db: DBDep):
    item = service.get_item(db, id)
    if not item:
        raise HTTPException(404, "Not found")
    return item

Typed Dependencies (Recommended)

from typing import Annotated

DBDep = Annotated[Session, Depends(get_db)]
UserDep = Annotated[User, Depends(get_current_user)]
SettingsDep = Annotated[Settings, Depends(get_settings)]

Error Handling

from fastapi import HTTPException, status

raise HTTPException(
    status_code=status.HTTP_404_NOT_FOUND,
    detail="Item not found"
)

Workflow

1. Define schemas (Pydantic) → Input validation + docs
2. Create endpoints → Route handlers with type hints
3. Add dependencies → DB, auth, settings injection
4. Write tests → TestClient + pytest
5. Deploy → Docker + Gunicorn/Uvicorn

Best Practices

• Use Annotated for reusable dependency types
• Separate schemas: Create, Update, Response, InDB
• Use response_model to control output shape
• Keep business logic in services, not routes
• Use async only when needed (DB, external APIs)
• Enable CORS early in development
• Add health check endpoint (/health)
• Use pydantic-settings for configuration