🧪 RESTful API with Python 3 and FastAPI

Proof of Concept for a RESTful Web Service built with FastAPI and Python 3.13. This project demonstrates best practices for building a layered, testable, and maintainable API implementing CRUD operations for a Players resource (Argentina 2022 FIFA World Cup squad).

Features

• 🏗️ Async Architecture - Async/await throughout with SQLAlchemy 2.0 and dependency injection via FastAPI's Depends()
• 📚 Interactive Documentation - Auto-generated Swagger UI with VS Code and JetBrains REST Client support
• ⚡ Performance Caching - In-memory caching with aiocache and async SQLite operations
• ✅ Input Validation - Pydantic models enforce request/response schemas with automatic error responses
• 🐳 Containerized Deployment - Production-ready Docker setup with migration-based database initialization
• 🔄 Automated Pipeline - Continuous integration with Black, Flake8, and automated testing

Tech Stack

Architecture

Layered architecture with dependency injection via FastAPI's Depends() mechanism and Pydantic for request/response validation.

%%{init: {
  "theme": "default",
  "themeVariables": {
    "fontFamily": "Fira Code, Consolas, monospace",
    "textColor": "#555",
    "lineColor": "#555"
  }
}}%%

graph RL

    tests[tests]

    main[main]
    routes[routes]
    fastapi[FastAPI]
    aiocache[aiocache]

    services[services]

    models[models]
    pydantic[Pydantic]

    schemas[schemas]

    databases[databases]
    sqlalchemy[SQLAlchemy]

    %% Strong dependencies

    routes --> main
    fastapi --> main

    fastapi --> routes
    aiocache --> routes
    services --> routes
    models --> routes
    databases --> routes

    schemas --> services
    models --> services
    sqlalchemy --> services
    pydantic --> models

    databases --> schemas
    sqlalchemy --> schemas
    sqlalchemy --> databases

    %% Soft dependencies

    sqlalchemy -.-> routes
    main -.-> tests

    %% Node styling with stroke-width
    classDef core fill:#b3d9ff,stroke:#6db1ff,stroke-width:2px,color:#555,font-family:monospace;
    classDef deps fill:#ffcccc,stroke:#ff8f8f,stroke-width:2px,color:#555,font-family:monospace;
    classDef test fill:#ccffcc,stroke:#53c45e,stroke-width:2px,color:#555,font-family:monospace;

    class main,routes,services,schemas,databases,models core
    class fastapi,sqlalchemy,pydantic,aiocache deps
    class tests test

Arrows follow the injection direction (A → B means A is injected into B). Solid = runtime dependency, dotted = structural. Blue = core domain, red = third-party, green = tests.

Significant architectural decisions are documented in docs/adr/.

API Reference

Interactive API documentation is available via Swagger UI at http://localhost:9000/docs when the server is running.

Error codes: 400 Bad Request (squad number mismatch on PUT) · 404 Not Found (player not found) · 409 Conflict (duplicate squad number on POST) · 422 Unprocessable Entity (schema validation failed)

For complete endpoint documentation with request/response schemas, explore the interactive Swagger UI.

Alternatively, use rest/players.rest with the REST Client extension for VS Code, or the built-in HTTP Client in JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm).

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.13+ — uses .python-version for automatic activation with pyenv, asdf, or mise
• uv (recommended) — fast Python package and project manager
• Docker & Docker Compose (optional, for containerized deployment)

Quick Start

Clone

git clone https://github.com/nanotaboada/python-samples-fastapi-restful.git
cd python-samples-fastapi-restful

Install

Dependencies are defined in pyproject.toml using PEP 735 dependency groups.

# Install uv (if you haven't already)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment and install all dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install --group dev

Run

# Apply database migrations (required once before the first run, and after
# docker compose down -v)
uv run alembic upgrade head

uv run uvicorn main:app --reload --port 9000

Access

Once the application is running, you can access:

• API Server: http://localhost:9000
• Swagger UI: http://localhost:9000/docs
• Health Check: http://localhost:9000/health

Containers

Build and Start

docker compose up

💡 Note: On first run, the entrypoint applies Alembic migrations (alembic upgrade head), which creates the database and seeds all 26 players. On subsequent runs, migrations are a no-op and the volume data is preserved.

Stop

docker compose down

Reset Database

To remove the volume and re-apply migrations from scratch on next start:

docker compose down -v

Pull Docker Images

Each release publishes multiple tags for flexibility:

# By semantic version (recommended for production)
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:1.0.0

# By coach name (memorable alternative)
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:ancelotti

# Latest release
docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:latest

Environment Variables

# Full async database URL (SQLite default, PostgreSQL compatible)
# SQLite (local/test):
DATABASE_URL=sqlite+aiosqlite:///./players-sqlite3.db
# PostgreSQL (Docker/production):
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/playersdb

# Legacy: SQLite file path — used only when DATABASE_URL is not set
STORAGE_PATH=./players-sqlite3.db

# Python output buffering: set to 1 for real-time logs in Docker
PYTHONUNBUFFERED=1

Contributi