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):

{
  "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):

{
  "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):

{
  "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 — Chi router choice
• ADR-0010 — v2 feature flag
• ADR-0013 — OpenAPI / Swagger toolchain
• ADR-0018 — User management & auth
• ADR-0021 — JWT secret retention
• ADR-0022 — Rate limiting + cache