dance-lessons-coach/documentation/API.md

# API endpoints

Reference document for all HTTP endpoints exposed by `dance-lessons-coach` server. The authoritative source is the swag-generated Swagger UI at `/swagger/index.html` (served by the Go binary). This markdown is the human-readable index, intentionally short — when in doubt, run the server and open Swagger.

## Conventions

- All paths under `/api/` (no other prefix is used)
- Versioned API under `/api/v1/<resource>` and `/api/v2/<resource>` (cf. ADR-0010 v2 feature flag)
- System / Health / Version endpoints at root (`/api/<endpoint>`, no version)
- Admin endpoints under `/api/admin/<action>` (require master admin password header)
- Response Content-Type: `application/json` unless documented otherwise
- Error envelope: `{"error":"<code>","message":"<text>"}` (HTTP 4xx/5xx)

## System endpoints (no auth)

| Method | Path | Purpose | Cf. |
|---|---|---|---|
| GET | `/api/health` | Liveness check (legacy, returns `{"status":"healthy"}`) | `pkg/server/server.go` |
| GET | `/api/healthz` | **Kubernetes-style** rich health: status / version / uptime_seconds / timestamp | PR #20 — handler with swag `@Router /healthz [get]` |
| GET | `/api/ready` | Readiness check (DB connection + service deps) | `pkg/server/server.go handleReadiness` |
| GET | `/api/version` | Version info (cached 60s, since PR #29) | `pkg/server/server.go handleVersion` |
| GET | `/api/info` | **Composite info aggregator**: version / commit_short / build_date / uptime_seconds / cache_enabled / healthz_status. Cached when cache is enabled (X-Cache: HIT/MISS header) | ADR-0026 — `pkg/server/server.go handleInfo` |

`/api/info` body schema (`InfoResponse`):

```json
{
  "version": "1.0.0",
  "commit_short": "abc12345",
  "build_date": "2026-05-05",
  "uptime_seconds": 1234,
  "cache_enabled": true,
  "healthz_status": "healthy",
  "go_version": "go1.26.1"
}
```

Use `/api/info` from a frontend footer or status page when you need version + uptime + cache state in a single round trip. The composite design avoids 3-4 chatty calls (`/version`, `/healthz`, `/ready`) when only a snapshot is needed.

`/api/healthz` body schema (`HealthzResponse`):

```json
{
  "status": "healthy",
  "version": "1.4.0",
  "uptime_seconds": 1234,
  "timestamp": "2026-05-04T08:00:00Z"
}
```

Use `/api/healthz` for kubelet liveness probes — richer than `/api/health` and stable.

## Admin endpoints (require X-Admin-Password header)

| Method | Path | Purpose | Cf. |
|---|---|---|---|
| POST | `/api/admin/cache/flush` | Flush the entire in-memory cache. Returns `{"flushed":true,"items_flushed":N,"timestamp":"..."}` (200) or `{"error":"unauthorized"}` (401) or `{"error":"cache_disabled"}` (503) | PR #29 — `pkg/server/server.go handleAdminCacheFlush` |

Auth: header `X-Admin-Password: <master-password>` (matches `auth.admin_master_password` in config / `DLC_AUTH_ADMIN_MASTER_PASSWORD` env var). Default `admin123` for local dev — **change in production**.

## v1 API (auth + greeting)

Mounted at `/api/v1/...` with the rate-limit middleware (cf. ADR-0022 Phase 1, since PR #22). Cached responses on greet (since PR #29).

### Auth (`/api/v1/auth/...`)

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/v1/auth/register` | User registration |
| POST | `/api/v1/auth/login` | Login with username + password, returns JWT |
| POST | `/api/v1/auth/validate` | Validate a JWT token |
| POST | `/api/v1/auth/password-reset/request` | Request password reset (admin-flagged users only) |
| POST | `/api/v1/auth/password-reset/complete` | Complete password reset |

JWT secret rotation policies: cf. ADR-0021 + JWT secrets endpoints under `/api/v1/admin/jwt/secrets` (admin-only).

### Greet (`/api/v1/greet/...`)

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/v1/greet?name=X` | Greeting (cached per name 60s, header `X-Cache: HIT/MISS`) |
| GET | `/api/v1/greet/{name}` | Greeting (path param variant, same caching) |

### Admin under v1 (`/api/v1/admin/...`)

JWT secret management endpoints.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/v1/admin/jwt/secrets` | List metadata (count + per-secret: is_primary, created_at_unix, expires_at_unix?, age_seconds, is_expired, sha256 fingerprint). **Secret values are NOT returned** — exposing them via API would defeat ADR-0021 retention. |
| `POST` | `/api/v1/admin/jwt/secrets` | Add a new JWT secret (body: `{secret, is_primary, expires_in}`) |
| `POST` | `/api/v1/admin/jwt/secrets/rotate` | Rotate to a new primary secret (body: `{new_secret}`) |

`GET` response shape (security: only fingerprint, no secret value):

```json
{
  "count": 2,
  "secrets": [
    {"is_primary": true, "created_at_unix": 1714900000, "age_seconds": 600, "is_expired": false, "secret_sha256": "a3f9c2..."},
    {"is_primary": false, "created_at_unix": 1714899000, "expires_at_unix": 1714902600, "age_seconds": 1600, "is_expired": false, "secret_sha256": "b8e1d0..."}
  ]
}
```

Cf. ADR-0021 + features/jwt/ BDD scenarios for the broader contract.

## v2 API

Enabled via `api.v2_enabled` config (cf. ADR-0010 v2 feature flag).

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/v2/greet` | v2 greeting (JSON body, more validation) |

## Swagger UI

Served at `/swagger/index.html` (and `/swagger/doc.json` for the embedded spec). Always reflects what the running binary exposes — when in doubt, prefer Swagger over this markdown.

## Cross-references

- [ADR-0002](../adr/0002-chi-router.md) — Chi router choice
- [ADR-0010](../adr/0010-api-v2-feature-flag.md) — v2 feature flag
- [ADR-0013](../adr/0013-openapi-swagger-toolchain.md) — OpenAPI / Swagger toolchain
- [ADR-0018](../adr/0018-user-management-auth-system.md) — User management & auth
- [ADR-0021](../adr/0021-jwt-secret-retention-policy.md) — JWT secret retention
- [ADR-0022](../adr/0022-rate-limiting-cache-strategy.md) — Rate limiting + cache