Task API

A containerized FastAPI task REST API backed by PostgreSQL and SQLAlchemy.

Quick start

cp .env.example .env
docker compose up --build
curl http://localhost:8000/health

The API is available at http://localhost:8000; interactive OpenAPI docs are at /docs.

For local development, create a virtual environment and run:

pip install -r requirements.txt
uvicorn app.main:app --reload
pytest -q

The default local database URL is PostgreSQL. Tests override the database dependency with isolated SQLite databases, so no database server is required for the test suite.

Configuration

Variable	Default	Description
DATABASE_URL	postgresql+psycopg2://tasks:tasks@db:5432/tasks	SQLAlchemy database URL
APP_NAME	Task API	API display name
LOG_LEVEL	INFO	Uvicorn log level

Do not commit production secrets. The Compose database uses the POSTGRES_* variables from .env and persists data in the postgres_data volume.

API contract

Tasks have a UUID id, required title (1–200 characters), optional description (maximum 5000), status (pending, in_progress, or completed), optional timezone-aware due_at, and server-managed UTC created_at and updated_at timestamps.

• POST /tasks — create; returns 201
• GET /tasks — list, with optional status, skip, and limit; returns 200
• GET /tasks/{id} — fetch; returns 200, or 404 if absent
• PATCH /tasks/{id} — partial update; returns 200, or 404
• DELETE /tasks/{id} — delete; returns 204, or 404
• GET /health — database-backed readiness check; returns 200 or 503

Invalid JSON, fields, UUIDs, or query parameters return a structured 422 response:

{"error":{"code":"VALIDATION_ERROR","message":"Request validation failed","details":[...]}}

Not-found and database failures use the same envelope with codes TASK_NOT_FOUND and DATABASE_ERROR. The API does not expose database internals.

Operations

docker compose up --build waits for the PostgreSQL health check before starting the API. On startup the API calls Base.metadata.create_all; this is convenient for this small service. For production, replace it with reviewed Alembic migrations before deploying schema changes. docker compose down preserves data; docker compose down -v removes the database volume.

Run pytest -q for CRUD, validation, status semantics, error envelopes, and persistence-isolation coverage.