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

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 `reference-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`