API

Kurzzusammenfassung

• Die Consumption-API liefert standardisierte read-only Daten an interne Konsumenten.
• Vertragsstabilität, Fehlercodes und Latenzgrenzen sind für produktive Nutzung verbindlich.
• Die API trägt einen klaren Decision-Support-Disclaimer und verweist auf Audit-Evidenzen.
• Änderungen erfolgen nur versioniert und rückwärtskompatibel innerhalb einer Major-Version.

Zweck

Verlässliche Schnittstelle für Reporting-, Risk- und Governance-Systeme auf Basis publizierter Signale.

Vertragsmodell

Endpunkte (Beispiel)

• GET /v1/signals
• GET /v1/signals/{entity_id}
• GET /v1/runs/{run_id}/metadata

Pflichtfelder in Responses

• run_id
• model_version
• data_as_of
• published_at
• trace_id
• decision_support_only=true

SLA/SLO

• SLA: API-Verfügbarkeit 99.9% pro Monat.
• SLO: p95 Antwortzeit ≤ 400 ms, p99 ≤ 800 ms.
• Datenlatenz: Neue Batch-Daten innerhalb von 15 Minuten nach Publish abrufbar.

Fehlerbehandlung

Code	Bedeutung	Client-Verhalten
400	Ungültige Parameter	Anfrage korrigieren
401/403	Auth/AuthZ fehlgeschlagen	Token/Rechte prüfen
404	Ressource nicht vorhanden	Kein Retry, fachlich behandeln
409	Versionskonflikt/inkompatible Anfrage	Endpoint-Version anpassen
429	Rate Limit	Backoff gemäss Retry-After
5xx	temporärer Serverfehler	Retries mit Exponential Backoff

Rollenrechte

• Nur authentifizierte interne Rollen erhalten Zugriff.
• Feldbasierte Sichtbarkeit nach Rolle (Need-to-know-Prinzip).
• Zugriff wird mit actor_id, Rolle und Zweckbezug geloggt.

Disclaimer und Audit-Referenzen

• API enthält in Metadaten den Hinweis: "Decision Support only".
• Jede Antwort ist auf scoring_run_id und model_version rückführbar.
• Für Governance-Reviews muss ein Audit-Trail exportierbar sein.

Entscheidung

• Versionierter API-Vertrag veröffentlicht.
• SLA/SLO und Datenlatenz gemessen.
• Fehlercodes und Retry-Regeln dokumentiert.
• Disclaimer und Audit-Rückverfolgbarkeit implementiert.