docs: restructure docs to diataxis and finalize DOCS-RESTRUCTURE-001

docs/reference-api.md

@@ -0,0 +1,55 @@
+# REST-API (v1)
+
+Letzte Aktualisierung: 2026-03-06
+
+## Single Source of Truth
+
+Die API-Spezifikation wird zentral gepflegt in:
+
+- `/docs/openapi.yaml`
+
+Diese Datei ist die verbindliche technische Referenz für:
+
+- Endpunkte
+- Request-/Response-Schemas
+- Statuscodes
+- Auth-Header
+
+## Fehlerhülle (API-Standard)
+
+Fehlerantworten nutzen ein einheitliches Schema:
+
+- `ok: false`
+- `request_id: <uuid>`
+- `error_code: <stable_machine_code>`
+- `details: { ... }`
+- kein Legacy-Feld `error` oder `errors`
+
+`request_id` wird zusaetzlich als Header `X-Request-Id` geliefert.
+Die `request_id` kommt zentral aus `RequestContext` und korreliert API-Fehler mit Audit-Einträgen.
+
+## API-Doku im Admin
+
+- UI: `/admin/api-docs`
+- Zugriff: Permission `api_docs.view`
+- Quelle der UI: `/docs/openapi.yaml`
+- Swagger UI ist read-only (kein `Try it out`).
+
+## Warum diese Seite kurz ist
+
+Diese Seite bleibt bewusst knapp, damit keine doppelte Pflege entsteht.
+
+Alle fachlichen und technischen API-Details stehen nur in `/docs/openapi.yaml`.
+
+## Änderungsprozess (verbindlich)
+
+1. API-Änderung immer zuerst in `/docs/openapi.yaml` pflegen.
+2. `/admin/api-docs` öffnen und Rendering kurz prüfen.
+3. API-Request per Client testen (z. B. Yaak/Postman/cURL).
+4. Nur falls nötig hier in `api.md` organisatorische Hinweise ergänzen (keine Endpoint-Details).
+
+## Verwandte Dokumente
+
+- Rate Limiting: `/docs/howto-anfragelimits.md`
+- Sicherheit/Permissions: `/docs/explanation-sicherheitsmodell.md`
+- Troubleshooting: `/docs/howto-fehlerbehebung.md`