# API Documentation Specification

## Requirements

### Functional Requirements

1. **OpenAPI Documentation**: Auto-generated at `/docs` and `/redoc`
2. **Health Endpoints**: `/health` and `/health/db` with comprehensive status
3. **Endpoint Documentation**: All endpoints have docstrings and Pydantic models
4. **API README**: `apps/api/README.md` with developer onboarding
5. **Architecture Decision Records**: Document key architectural choices

### Non-Functional Requirements

1. **Performance**: Health checks complete in < 100ms
2. **Security**: Health endpoints don't expose sensitive data
3. **Maintainability**: Documentation stays in sync with code

## API Specification

### GET /health

Returns overall system health status.

**Response 200:**
```json
{
  "status": "healthy",
  "timestamp": "2026-05-19T12:00:00Z",
  "version": "0.1.0",
  "checks": {
    "database": {
      "status": "healthy",
      "response_time_ms": 5.2
    },
    "disk": {
      "status": "healthy",
      "free_gb": 45.2,
      "total_gb": 100.0
    }
  },
  "uptime_seconds": 3600
}
```

### GET /health/db

Returns database-specific health status.

**Response 200:**
```json
{
  "status": "healthy",
  "response_time_ms": 5.2
}
```

### GET /docs

FastAPI Swagger UI (auto-generated).

### GET /redoc

FastAPI ReDoc (auto-generated).

## Documentation Requirements

### Endpoint Docstrings

Every endpoint must have:
- Description of what it does
- Request/response model descriptions
- Authentication requirements
- Error responses

### Pydantic Models

Every model must have:
- `description` field metadata
- Example values where helpful
- Proper typing

### API README Structure

```markdown
# Headquarter API

## Overview
## Quick Start
## Environment Variables
## Development
## Testing
## Architecture
## Deployment
```

## ADR Template

```markdown
# ADR-XXX: Title

## Status
Accepted

## Context
What is the issue we're facing?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

## Date
2026-05-19
```

## Quality Gates

- `/docs` loads successfully
- `/health` returns 200 with valid JSON
- `/health/db` returns database status
- All endpoints have docstrings
- API README is complete
- At least one ADR exists