Hosting-Backoffice/architecture/api-strategy-v0.2.md

API Strategy v0.2

Zweck

Dieses Dokument konkretisiert API-first nach dem Architekturreview.

Kurz erklärt

API-first bedeutet:

Die Schnittstelle wird als Vertrag geplant,
nicht nachträglich aus Controllern abgeleitet.

Entscheidung

V1 verwendet REST API mit OpenAPI 3.x als Spezifikation.

OpenAPI

OpenAPI ist eine maschinenlesbare Beschreibung der API.

Sie definiert:

• Endpoints
• Datenformate
• Auth
• Fehler
• Parameter
• Responses

API-Konventionen

Versionierung

/api/v1/

Pagination

Cursor Pagination wird bevorzugt.

Fehlerformat

Problem Details nach RFC 7807 wird als Zielmodell verwendet.

Idempotenz

Für kritische POST-Vorgänge wird ein Idempotency-Key vorbereitet.

Idempotenz bedeutet:

Ein Vorgang kann mehrfach gesendet werden,
ohne mehrfach ausgeführt zu werden.

Filtering

filter[status]=active
filter[customer_id]=123

Sorting

sort=-created_at

Auth

V1 nutzt Laravel Sanctum gemäß ADR 0006.

Long Running Jobs

Lange Vorgänge laufen asynchron.

Beispiele:

• große Importe
• Syncs
• spätere Migrationen

Sie erhalten Job-Status-Endpunkte.

Webhooks

Webhooks sind nicht V1-Pflicht, werden aber architektonisch vorbereitet.

Webhook bedeutet:

Das System informiert andere Systeme automatisch,
wenn ein Ereignis passiert.

Nächster Schritt

OpenAPI-Stub für V1 erstellen.