---

name: task-management-api description: Task Management REST API built with FastAPI, SQLModel, and UV using Test-Driven Development. This skill should be used when building task/todo APIs, learning TDD with FastAPI, or as a reference for SQLModel + FastAPI integration. allowed-tools: Bash(uv:), Bash(pytest:), Bash(python:*), Read, Glob, Grep, Write, Edit

Task Management API

A production-ready Task Management REST API built with FastAPI + SQLModel + UV using Test-Driven Development (TDD).

Before Implementation

Gather context before building or extending this API:

Clarifications

Required (ask if extending)

1. New entity? Tasks only / Add users / Add categories
2. Database? Neon PostgreSQL / SQLite (local dev)
3. Authentication? JWT / API Key / None

Optional

1. Additional fields? Tags / Attachments / Comments
2. Filtering needs? By status / By priority / By date range

Official Documentation

Version Note: Built with FastAPI 0.100+, SQLModel 0.0.16+, Python 3.12+.

Features

• Full CRUD operations (Create, Read, Update, Delete)
• Task priority levels (low, medium, high, urgent)
• Task status tracking (pending, in_progress, completed, cancelled)
• Due date management
• Filtering and pagination
• Neon Serverless PostgreSQL support (with SQLite fallback)
• SQLModel ORM for database operations
• Comprehensive test suite with pytest
• UV package manager for fast dependency management

Quick Start

Installation

Copycd task-management-api
uv sync

Database Setup (Neon)

1. Create account at neon.tech
2. Create a new project
3. Copy connection string and create .env:

Copycp .env.example .env
# Edit .env with your Neon connection string:
# DATABASE_URL=postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require

Without .env, the app uses SQLite for local development.

Run Tests

Copyuv run pytest -v
uv run pytest --cov=app --cov-report=term-missing

Run Server

Copyuv run fastapi dev app/main.py

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Project Structure

Copytask-management-api/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application
│   ├── database.py          # Database configuration
│   ├── models/
│   │   ├── __init__.py
│   │   └── task.py          # Task SQLModel models
│   └── routers/
│       ├── __init__.py
│       └── tasks.py         # Task CRUD endpoints
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # Test fixtures
│   └── test_tasks.py        # Task API tests
├── pyproject.toml
└── README.md

API Endpoints

Task Model

Copyclass Task(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    title: str = Field(index=True)
    description: str | None = None
    status: TaskStatus = Field(default=TaskStatus.PENDING)
    priority: TaskPriority = Field(default=TaskPriority.MEDIUM)
    due_date: datetime | None = None
    created_at: datetime = Field(default_factory=datetime.utcnow)
    updated_at: datetime = Field(default_factory=datetime.utcnow)

TDD Workflow

This project follows strict TDD practices:

1. RED Phase - Write Failing Test

Copydef test_create_task(client):
    response = client.post("/tasks/", json={
        "title": "Complete project",
        "priority": "high"
    })
    assert response.status_code == 201
    assert response.json()["title"] == "Complete project"

2. GREEN Phase - Implement Minimal Code

Copy@router.post("/", response_model=TaskRead, status_code=201)
def create_task(task: TaskCreate, session: Session = Depends(get_session)):
    db_task = Task.model_validate(task)
    session.add(db_task)
    session.commit()
    session.refresh(db_task)
    return db_task

3. REFACTOR Phase - Improve Code Quality

Add validation, error handling, indexes while keeping tests green.

Example Requests

Create Task

Copycurl -X POST http://localhost:8000/tasks/ \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn FastAPI", "priority": "high", "status": "pending"}'

List Tasks

Copycurl http://localhost:8000/tasks/

Update Task

Copycurl -X PATCH http://localhost:8000/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

Delete Task

Copycurl -X DELETE http://localhost:8000/tasks/1

References

• TDD Guide - Test-Driven Development practices
• FastAPI Integration - SQLModel + FastAPI patterns
• Testing Patterns - FastAPI testing best practices

Development

Run Specific Test

Copyuv run pytest tests/test_tasks.py::test_create_task -v

Watch Mode (Continuous TDD)

Copyuv add pytest-watch --dev
uv run ptw -- -v

Coverage Report

Copyuv run pytest --cov=app --cov-report=html
open htmlcov/index.html

Common Mistakes

Before Delivery Checklist

API Quality

• All CRUD endpoints working
• Proper HTTP status codes (201, 204, 404)
• Input validation via Pydantic
• Error responses are consistent

Database

• .env configured for target database
• Models have proper indexes
• Timestamps auto-generated

Testing

• All tests pass: uv run pytest -v
• Coverage acceptable: uv run pytest --cov=app
• TDD followed (tests written first)

Documentation

• Swagger UI accessible at /docs
• Endpoints have proper tags
• Request/response examples visible