by nanotaboada
🧪 Proof of Concept for a RESTful API built with Python 3 and FastAPI
# Add to your Claude Code skills
git clone https://github.com/nanotaboada/python-samples-fastapi-restfulNo comments yet. Be the first to share your thoughts!
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).
Depends()| 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 |
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/.
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).
Before you begin, ensure you have the following installed:
git clone https://github.com/nanotaboada/python-samples-fastapi-restful.git
cd python-samples-fastapi-restful
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) |
uv run uvicorn main:app --reload --port 9000
Once the application is running, you can access:
http://localhost:9000http://localhost:9000/docshttp://localhost:9000/healthdocker 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.
docker compose down
To remove the volume and reinitialize the database from the built-in seed file:
docker compose down -v
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
# 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
Contributions are welcome! Please see CONTRIBUTING.md for details on:
Key guidelines:
uv run pytest)uv run black . before committing