Fast API Starter

fast-api-starter is a FastAPI reference starter using uv, Pydantic, async SQLAlchemy, PostgreSQL, pytest, Ruff, and a small project-management API.

It is intentionally not Clean Architecture. The structure follows common FastAPI conventions: API routes, core runtime setup, database models, schemas, repositories, and services.

Features

• FastAPI application with lifespan startup
• Pydantic settings through pydantic-settings
• Pydantic request and response schemas
• Async SQLAlchemy 2.0 with PostgreSQL
• Local PostgreSQL through Docker Compose
• Health endpoint
• Project CRUD-style sample endpoints
• Pagination with limit and offset
• Structured JSON-friendly logging configuration
• X-Request-ID response header for request correlation
• Problem Details error responses
• Uvicorn Server response header disabled in first-party run commands
• CORS configuration from settings
• pytest tests with HTTPX ASGI transport
• Ruff formatting and linting
• uv for dependency management and task execution

Requirements

• Python 3.12+
• Docker Desktop
• uv

Install uv and Python

This project uses uv to manage Python, the virtual environment, dependencies, and command execution.

Install uv on macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal after installation, or reload your shell:

source ~/.zshrc

Verify uv is available:

uv --version

If Python is not installed, let uv install it:

uv python install 3.12

You do not need to run uv venv manually for normal setup. uv sync creates and uses the project .venv automatically.

Setup

cp .env.example .env
uv sync
docker compose up -d
uv run uvicorn fast_api_starter.main:app --app-dir src --reload --no-server-header

Open:

• API: http://localhost:8000
• Version: http://localhost:8000/version
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Every HTTP response includes X-Request-ID. If a request sends this header, the same value is returned. Otherwise, the API generates a new request id.

Error responses use application/problem+json with type, title, status, instance, and requestId. Validation errors also include an errors collection.

CI and Security

GitHub Actions workflows live in .github/workflows:

• build.yml installs dependencies with uv, checks Ruff formatting, runs Ruff linting, and runs pytest.
• codeql.yml runs CodeQL static security analysis on pull requests, pushes to main, and weekly on Monday.

Dependabot is configured for Python dependencies and GitHub Actions updates.

Common Commands

uv run uvicorn fast_api_starter.main:app --app-dir src --reload --no-server-header
uv run pytest
uv run ruff format .
uv run ruff check .

Or use scripts:

scripts/dev.sh
scripts/test.sh
scripts/lint.sh

Project Layout

fast-api-starter
├── src
│   └── fast_api_starter
│       ├── api
│       │   └── routes
│       ├── core
│       ├── db
│       ├── models
│       ├── repositories
│       ├── schemas
│       └── services
└── tests

API Examples

Create a project:

curl -X POST http://localhost:8000/api/projects \
  -H 'Content-Type: application/json' \
  -d '{"name":"Template API","description":"Build the starter"}'

List projects:

curl 'http://localhost:8000/api/projects?limit=20&offset=0'

Configuration

Settings are loaded from environment variables and .env:

APP_NAME=Fast API Starter
ENVIRONMENT=development
LOG_LEVEL=INFO
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/postgres
CREATE_TABLES_ON_STARTUP=true
CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]

CREATE_TABLES_ON_STARTUP=true is convenient for this starter. For production systems, prefer migrations with Alembic.