# API Documentation - Design

## Architecture

```
API Documentation
├── OpenAPI (FastAPI native)
│   ├── /docs (Swagger UI)
│   ├── /redoc (ReDoc)
│   └── /openapi.json
├── Health Endpoints
│   ├── GET /health
│   └── GET /health/db
├── API README
│   └── apps/api/README.md
└── Architecture Decision Records
    └── docs/architecture/decisions/
```

## Component Design

### OpenAPI Documentation

FastAPI automatically generates OpenAPI schema from:
- Pydantic models (request/response)
- Endpoint docstrings
- Path operation parameters
- Response status codes

**Enhancements needed:**
- Add descriptions to all Pydantic models
- Add docstrings to all endpoints
- Add response examples where helpful
- Add authentication requirements

### Health Endpoints

**GET /health**
```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**
```json
{
  "status": "healthy",
  "response_time_ms": 5.2,
  "connections": {
    "active": 2,
    "idle": 3,
    "max": 20
  }
}
```

### API README

**Sections:**
1. Overview
2. Quick Start
3. Environment Variables
4. Development Setup
5. Running Tests
6. Architecture Overview
7. Common Commands
8. Deployment

### Architecture Decision Records

**Format:**
- Title
- Status (proposed, accepted, deprecated)
- Context
- Decision
- Consequences
- Date

**ADRs to create:**
1. Session-based authentication (vs JWT)
2. SQLAlchemy async with PostgreSQL
3. Docker-based tool instances

## Technical Details

**Libraries:**
- FastAPI (built-in OpenAPI)
- Pydantic v2 (schemas)
- psutil (disk/health metrics)

**Files to modify:**
- `apps/api/src/main.py` - Add health endpoints
- All `apps/api/src/api/*.py` - Add docstrings
- All `apps/api/src/models/*.py` - Add model descriptions
- `apps/api/src/schemas/*.py` - Add response schemas

## Error Handling

- Health endpoints return 200 even if degraded
- Failed checks included in response with "degraded" status
- Never expose sensitive info in health responses