REST API in FastAPI

A FastAPI project scaffolded for growth: versioned API routes, centralized settings, and a test suite from day one.

Structure

app/
  main.py              # FastAPI app factory, middleware, top-level routes
  core/
    config.py          # Settings (env-driven, cached)
  api/
    v1/
      router.py         # Aggregates all v1 endpoint routers
      endpoints/
        hello.py         # GET /api/v1/hello
tests/
  test_hello.py
docker/
  Dockerfile           # Production image
  Dockerfile.dev        # Development image (hot reload)
  docker-compose.yml    # Runs the production image
  docker-compose.dev.yml # Runs the dev image with live reload

Add new features as a new module under app/api/v1/endpoints/, then register its router in app/api/v1/router.py. When a v2 is needed, add app/api/v1 alongside a new app/api/v2 and mount both in app/main.py.

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env

Run

uvicorn app.main:app --reload

Visit http://127.0.0.1:8000/docs for the interactive API docs.

Test

pytest

Docker

The project is fully containerized — see docker/README.md for details. All commands run from the project root.

Production:

docker compose -f docker/docker-compose.yml up --build

Development (hot reload, mounts app/ and tests/):

docker compose -f docker/docker-compose.dev.yml up --build

Both serve the API at http://localhost:8000 (docs at /docs, health check at /health). Requires a .env file at the project root (copy from .env.example).

To stop and remove containers:

docker compose -f docker/docker-compose.yml down