headquarter/openspec/changes/api-documentation/tasks.md

API Documentation - Tasks

Phase 1: Health Endpoints

• Task 1.1: Enhance /health endpoint

  • Add timestamp, version, uptime
  • Add disk space check
  • Add comprehensive checks object
  • Create HealthCheck Pydantic models

• Task 1.2: Create /health/db endpoint

  • Database connection check
  • Response time measurement
  • Connection pool status

Phase 2: Endpoint Documentation

• Task 2.1: Document auth endpoints

  • Add docstrings to src/api/auth.py
  • Add response model descriptions
  • Add error responses

• Task 2.2: Document projects endpoints

  • Add docstrings to src/api/projects.py
  • Document request/response models

• Task 2.3: Document repositories endpoints

  • Add docstrings to src/api/git_repositories.py
  • Document file operations

• Task 2.4: Document user endpoints

  • Add docstrings to src/api/users.py
  • Document profile endpoints

• Task 2.5: Document tool endpoints

  • Add docstrings to src/api/tool_types.py
  • Add docstrings to src/api/tool_instances.py

• Task 2.6: Document SSH keys endpoints

  • Add docstrings to src/api/ssh_keys.py

• Task 2.7: Document config endpoints

  • Add docstrings to src/api/user_config.py

• Task 2.8: Document dashboard endpoint

  • Add docstrings to src/api/dashboard.py

• Task 2.9: Document terminal endpoint

  • Add docstrings to src/api/terminal.py

Phase 3: Model Documentation

• Task 3.1: Document Pydantic models
  • Add descriptions to all response models
  • Add example values
  • Document in src/schemas/ or inline

Phase 4: API README

• Task 4.1: Create apps/api/README.md
  • Overview section
  • Quick start guide
  • Environment variables table
  • Development setup
  • Testing instructions
  • Architecture overview
  • Common commands

Phase 5: Architecture Decision Records

• Task 5.1: Create ADR for session auth

  • Document why cookies vs JWT
  • Trade-offs and risks

• Task 5.2: Create ADR for async SQLAlchemy

  • Document async pattern choice
  • PostgreSQL decision

Phase 6: Quality Gates

• Task 6.1: Verify /docs endpoint

  • Check all endpoints appear
  • Verify schemas are documented

• Task 6.2: Verify health endpoints

  • Test /health
  • Test /health/db

• Task 6.3: Run linting

  • ruff check
  • mypy

• Task 6.4: Run tests

  • pytest