Contract-First Task Tracker API

A demonstration of contract-first API development using FastAPI and OpenAPI.

Overview

This project demonstrates how to build APIs using a contract-first approach where the OpenAPI specification is written first, and the implementation follows the spec exactly.

Quick Start

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
make install

# Run the server
make dev

The API will be available at http://localhost:8000.

API Endpoints

Method	Endpoint	Description
POST	/tasks	Create a new task
GET	/tasks	List all tasks (with filtering)
GET	/tasks/{id}	Get a specific task
PATCH	/tasks/{id}	Update a task
DELETE	/tasks/{id}	Delete a task

Example Usage

# Create a task
curl -X POST http://localhost:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Review pull request", "priority": "high"}'

# List all tasks
curl http://localhost:8000/tasks

# Get the OpenAPI spec
curl http://localhost:8000/openapi.yaml

Running Tests

make test

Project Structure

contract-first-task-tracker/
├── openapi.yaml          # The contract (source of truth)
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI application
│   ├── storage.py        # In-memory storage
│   └── routes/
│       └── tasks.py      # Task endpoints
├── tests/
│   └── test_tasks.py     # API tests
├── requirements.txt
├── Makefile
└── README.md

Learn More

Read the full blog post: Contract-First API Development