REST API

Status: Entwurf · Spec-Kandidat: ja

Pflicht (FR-013, NFR-007)

Alle REST-Routen liegen unter /api/v1/... ab Tag 1.
OpenAPI-Spec ist Build-Artefakt — Backend-Build erzeugt openapi.yaml als CI-Asset.
Breaking-Changes laufen über parallele Major-Versionen (/api/v2/..., parallel betrieben).
Sunset-Policy: deprecated Major-Versionen bleiben mindestens 6 Monate parallel verfügbar; ab Deprecation-Beschluss werden Sunset- und Deprecation-Header gesetzt.
Minor-Änderungen sind additiv (neue Felder, neue Endpoints) und versionieren nicht — Konsumenten ignorieren unbekannte Felder.

Ressource	Pfad-Skizze	Beschreibung
Entitätstypen	`/entity-types`	CRUD auf `DDM_ENTITY_TYPE`
Attributdefinitionen	`/entity-types/{key}/attributes`	CRUD auf `DDM_ENTITY_TYPE_ATTRIBUTE`
Enum-Sets	`/enum-sets`, `/enum-sets/{key}/values`	CRUD auf `DDM_ENUM_SET` und `DDM_ENUM_VALUE`
Relationstypen	`/relation-types`	CRUD auf `DDM_RELATION_TYPE`
Entitäten	`/entities`, `/entities/{id}`	CRUD auf `DDM_ENTITY`
Beziehungen	`/entities/{id}/relations`, `/relations/{id}`	CRUD auf `DDM_ENTITY_RELATION`
Suche	`/entities/search`	strukturierte und Volltextsuche
Audit	`/audit/entries`	Lesezugriff für Auditor-Rolle
Versionssnapshots	`/entities/{id}/versions`	Lesezugriff

Diese Pfade sind Vorschläge für die spätere API-Spec und nicht final.

Transaktionsklammer pro Request: bei Schreibvorgängen werden Validierung, Datenänderung, AA_AUDIT_LOG und ggf. DDM_ENTITY_VERSION in einer Transaktion gebündelt. Verbindliche Reihenfolge: siehe Abläufe – Verbindliche Reihenfolge in einer Mutationstransaktion.
Auth: jeder Request trägt einen OIDC-Access-Token. Identitäten landen in created_by / updated_by / changed_by.
Korrelation: Eingehender X-Correlation-Id-Header wird in AA_AUDIT_LOG.correlation_id übernommen, sonst neu generiert.
Fehlermodell: konsistent strukturiert (z. B. RFC 7807 / Problem Details), mit Feldzuordnung bei Validierungsfehlern.
Pagination: Cursor-basiert empfohlen.

Situation	Status
Kein/ungültiges Token	`401 Unauthorized`
Authentifiziert, Aufrufer hat keine `read`-Permission auf die Ressource	`404 Not Found` (identisch zu nicht existent — kein Existenzleak)
Authentifiziert, `read` erlaubt, aber angeforderte Aktion (`update`/`delete`/`relate`) verweigert	`403 Forbidden`
Tenant-Mismatch (Header-Override gegen aktive Rolle in anderem Tenant)	`403 Forbidden`
Validierungsfehler	`400 Bad Request` (oder `422 Unprocessable Entity`) mit RFC 7807
Idempotenz-Konflikt / `code` doppelt	`409 Conflict`

Filter über Query-Parameter (?entity_type=customer&status=active&attributes.industry=banking).
Volltextsuche über separaten ?q=-Parameter, intern auf search_vector.

Wahl der API-Stilrichtung (REST mit JSON, JSON:API, oder GraphQL ergänzend) ist nicht festgelegt.
Konkrete Pfad-Schreibweise (kebab-case vs. snake_case) ist offen.
Versionierung: URL-Pfad (/v1) oder Header-basiert.
Bulk-Endpoints (Import/Export, FR-103) sind separat zu spezifizieren.