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 pre-seeded database
• 🔄 Automated Pipeline - Continuous integration with Black, Flake8, and automated testing

Tech Stack

| Category | Technology | | -------- | ---------- | | Language | Python 3.13 | | Web Framework | FastAPI + Uvicorn | | ORM | SQLAlchemy 2.0 (async) + aiosqlite | | Database | SQLite | | Validation | Pydantic | | Caching | aiocache (in-memory, 10-minute TTL) | | Testing | pytest + pytest-cov + httpx | | Linting / Formatting | Flake8 + Black | | Containerization | Docker & Docker Compose |

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.

| Method | Endpoint | Description | Status | | ------ | -------- | ----------- | ------ | | GET | /players/ | List all players | 200 OK | | GET | /players/{player_id} | Get player by ID | 200 OK | | GET | /players/squadnumber/{squad_number} | Get player by squad number | 200 OK | | POST | /players/ | Create new player | 201 Created | | PUT | /players/squadnumber/{squad_number} | Update player by squad number | 204 No Content | | DELETE | /players/squadnumber/{squad_number} | Remove player by squad number | 204 No Content | | GET | /health | Health check | 200 OK |

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

| Command | Description | | ------- | ----------- | | uv pip install | Production dependencies only | | uv pip install --group test | Test dependencies | | uv pip install --group lint | Linting dependencies | | uv pip install --group dev | All (test + lint + production) |

Run

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 container copies a pre-seeded SQLite database into a persistent volume. On subsequent runs, that volume is reused and the data is preserved.

Stop

docker compose down

Reset Database

To remove the volume and reinitialize the database from the built-in seed file:

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

# Database storage path (default: ./storage/players-sqlite3.db)
STORAGE_PATH=./storage/players-sqlite3.db

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

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on:

• Code of Conduct
• Development workflow and best practices
• Commit message conventions (Conventional Commits)
• Pull request process and requirements

Key guidelines:

• Follow Conventional Commits for commit messages
• Ensure all tests pass (uv run pytest)
• Run uv run black . before committing
• Keep