beug.k@beugsiud.deandClaude Opus 5.5
eb1fa0b2e4
- 0016: verified edition, signature scheme and feature set; build-time account/public key, nonce, fingerprint, grace semantics, license files - 0019: OpenAPI contract tests instead of generated server stubs - 0020: Argon2id, TOTP, OIDC with PKCE, sessions, CSRF, rate limits, RBAC Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1.0 KiB
1.0 KiB
0012 – API: OpenAPI als Single Source of Truth
- Status: Akzeptiert, Server-Teil ersetzt durch 0019
- Datum: 2026-10-12
Entscheidung
- Die REST-API wird in
server/api/openapi.yaml(OpenAPI 3.0.3) beschrieben. Die Datei ist die verbindliche Quelle. - Server: oapi-codegen v2 erzeugt Typen und ein striktes Server-Interface für
net/http. Fehlt eine Implementierung, kompiliert der Server nicht. - Frontend: openapi-typescript erzeugt Typen, openapi-fetch dient als typisierter Client.
- Generierter Code wird eingecheckt, die CI prüft per Neugenerierung und
git diff, dass er aktuell ist. - API-Version im Pfad (
/api/v1). Felder insnake_case, Englisch. Fehlerantworten im Format RFC 9457 (application/problem+json) mit stabilemcode; der deutsche Text für die Oberfläche kommt aus der Übersetzung des Codes, nicht aus dem Server-Log.
Konsequenzen
Server und Client können nicht unbemerkt auseinanderlaufen. docs/API.md verweist auf die Spezifikation, statt sie zu duplizieren.