breadcrumb-the-shire/docs/reference-api.md

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