🧪 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

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 changes small and focused
• Review .github/copilot-instructions.md for architectural patterns

Testing:

Run the test suite with pytest:

# Run all tests
uv run pytest

# Run tests with coverage report
uv run pytest --cov=./ --cov-report=term

Command Summary

Legal

This project is provided for educational and demonstration purposes and may be used in production at your own discretion. All trademarks, service marks, product names, company names, and logos referenced herein are the property of their respective owners and are used solely for identification or illustrative purposes.