REST-API (v1)

Letzte Aktualisierung: 2026-03-24

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)

API-Änderung immer zuerst in /docs/openapi.yaml pflegen.
/admin/api-docs öffnen und Rendering kurz prüfen.
API-Request per Client testen (z. B. Yaak/Postman/cURL).
Nur falls nötig hier in reference-api.md organisatorische Hinweise ergänzen (keine Endpoint-Details).

1.5 KiB Raw Blame History