Building REST APIs with FastAPI — A Complete Guide

Introduction

FastAPI has quietly become the default choice for new Python backends. It's fast (on par with Node and Go for I/O-bound work), it generates OpenAPI docs for free, and its dependency injection system makes testing genuinely pleasant. This guide builds a production-shaped REST API from an empty folder to a Dockerized service backed by Postgres.

If you're coming from Spring Boot, the mental model maps cleanly — see the Java equivalent at Building REST APIs with Spring Boot for a side-by-side comparison.

Key takeaways

• FastAPI uses Python type hints as the contract for validation, serialization and OpenAPI docs.
• Pydantic v2 is the equivalent of Spring's DTO + Jakarta Validation, but ~10× faster.
• Dependency injection is built in — no third-party container required.
• Async endpoints are a real performance win for I/O-bound workloads; CPU-bound work belongs in a worker.
• A clean project structure (routers → services → repositories) scales from one developer to a team.

Project structure

app/
  main.py            # FastAPI() + router registration
  api/
    v1/
      users.py       # router
      items.py
  core/
    config.py        # pydantic-settings
    security.py
  db/
    base.py          # SQLAlchemy Base + engine
    session.py
  models/            # SQLAlchemy ORM models
  schemas/           # Pydantic request/response models
  services/          # business logic
  repositories/      # data access

Package-by-feature works just as well — pick one and enforce it.

Step 1 — Bootstrap the app

pip install "fastapi[standard]" "sqlalchemy[asyncio]" asyncpg pydantic-settings

```python
# app/main.py
from fastapi import FastAPI
from app.api.v1 import users, items

app = FastAPI(title="MasterLab API", version="1.0.0") app.include_router(users.router, prefix="/api/v1/users", tags=["users"]) app.include_router(items.router, prefix="/api/v1/items", tags=["items"]) ```

fastapi dev app/main.py

Open http://localhost:8000/docs — Swagger UI is generated from your type hints, with no annotations or YAML.

Step 2 — Pydantic models (your DTOs)

```python
# app/schemas/user.py
from pydantic import BaseModel, EmailStr, Field
from datetime import datetime

class UserCreate(BaseModel): email: EmailStr full_name: str = Field(min_length=1, max_length=120) password: str = Field(min_length=8, max_length=128)

class UserOut(BaseModel): id: int email: EmailStr full_name: str created_at: datetime

model_config = {"from_attributes": True} ```

Validation is automatic — a malformed request returns a structured 422 with field-level errors.

Step 3 — Async SQLAlchemy

```python
# app/db/session.py
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine

engine = create_async_engine(settings.DATABASE_URL, pool_size=10, pool_pre_ping=True) SessionLocal = async_sessionmaker(engine, expire_on_commit=False)

async def get_session(): async with SessionLocal() as session: yield session ```

```python
# app/models/user.py
from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase
from datetime import datetime

class Base(DeclarativeBase): ...

class User(Base): __tablename__ = "users" id: Mapped[int] = mapped_column(primary_key=True) email: Mapped[str] = mapped_column(unique=True, index=True) full_name: Mapped[str] password_hash: Mapped[str] created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow) ```

Step 4 — Dependency injection

```python
# app/api/v1/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from app.db.session import get_session
from app.schemas.user import UserCreate, UserOut
from app.services.user_service import UserService

router = APIRouter()

def get_user_service(db: AsyncSession = Depends(get_session)) -> UserService: return UserService(db)

@router.post("", response_model=UserOut, status_code=status.HTTP_201_CREATED) async def create_user( payload: UserCreate, svc: UserService = Depends(get_user_service), ): user = await svc.create(payload) if user is None: raise HTTPException(409, "Email already registered") return user ```

The Depends() graph is constructed per-request, so testing means overriding one function.

Step 5 — Error handling

```python
from fastapi import Request
from fastapi.responses import JSONResponse

class DomainError(Exception): def __init__(self, code: str, message: str, status: int = 400): self.code, self.message, self.status = code, message, status

@app.exception_handler(DomainError) async def domain_error_handler(_: Request, exc: DomainError): return JSONResponse(status_code=exc.status, content={"code": exc.code, "message": exc.message}) ```

Step 6 — Dockerize

FROM python:3.12-slim AS base
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", \
     "-w", "4", "-b", "0.0.0.0:8000"]

Production best practices

• Use Gunicorn + UvicornWorker in production, not bare uvicorn --reload.
• Pin Pydantic, FastAPI and SQLAlchemy in requirements.txt — minor versions matter.
• Put all settings in pydantic-settings and load from env vars, never from disk.
• Return explicit response_model on every route — no leaked password hashes.
• Add a /healthz and /readyz endpoint for Kubernetes probes.

Common mistakes

• Mixing def and async def endpoints carelessly — sync endpoints run on a threadpool and silently throttle concurrency under load.
• Calling requests (sync) from an async endpoint — use httpx.AsyncClient.
• Forgetting expire_on_commit=False — accessing ORM attributes after commit triggers a lazy load and crashes in async code.

Tools used in this tutorial

The setup below uses the following tools. Versions matter less than the role each one plays, so swap freely as long as you keep the responsibilities the same.

• Python 3.12+
• FastAPI
• Uvicorn / Gunicorn
• Pydantic v2
• SQLAlchemy 2.x
• Docker
• Kubernetes

Real-world production context

In production, a Python backend like this rarely runs as a single uvicorn process on a laptop. Teams build the app into a container image, push it to a registry, and run it behind a managed load balancer with autoscaling, health checks and centralized logging. Async FastAPI services typically use multiple Uvicorn workers managed by Gunicorn, a managed Postgres for state, Redis for cache and rate-limit counters, and an object store for uploads. The reason cloud hosting becomes a hard requirement is operational: zero-downtime rollouts, log aggregation, metrics, and TLS at the edge are not optional once real users depend on the API.

Recommended tools & deployment options

Once the tutorial works on your machine, the next question is *where do I run this for real?* These are the platforms most Python backend teams reach for:

• DigitalOcean — the simplest path from a working FastAPI container to a public URL. App Platform deploys directly from a Dockerfile, managed Postgres and Redis are one click away, and pricing is predictable. A common way to deploy the setup in this tutorial is using a cloud provider like DigitalOcean when you want to ship quickly without learning a full cloud SDK.
• AWS — the default for enterprise workloads. ECS Fargate or EKS run containers without you managing servers, RDS handles Postgres, and CloudWatch covers logs and metrics.
• Docker — the packaging format every modern deploy target understands. Build once, run the same image locally, in CI and in production.
• Kubernetes (managed: EKS, DOKS, GKE) — the right choice once you have more than a handful of services, need rolling updates, autoscaling and policy-driven networking.

A VPS or managed cloud service is required to run this architecture end-to-end — uvicorn --reload is for development, not for serving traffic.

FAQ

Is FastAPI production-ready? Yes — Netflix, Microsoft and Uber publicly run it at scale.

FastAPI vs Flask? Flask is sync-first and has no built-in validation. FastAPI gives you async, validation and docs for free. New projects should default to FastAPI.

Do I need async everywhere? No. Use async for I/O-bound endpoints (DB, HTTP, Redis). Pure CPU work belongs in a Celery/RQ worker.

Next steps & related tutorials

Keep the momentum going with the next tutorial in this learning path:

• Next: FastAPI Microservices Architecture Explained Step by Step
• Next: Dockerizing a FastAPI Application the Right Way
• Next: JWT Authentication in FastAPI — Secure APIs Properly
• Next: Java equivalent: Building REST APIs with Spring Boot