Add AI workspace reviews

architecture/api-strategy-v0.2.md

@@ -0,0 +1,91 @@
+# API Strategy v0.2
+
+## Zweck
+Dieses Dokument konkretisiert API-first nach dem Architekturreview.
+
+## Kurz erklärt
+API-first bedeutet:
+
+```text
+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
+
+```text
+/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:
+
+```text
+Ein Vorgang kann mehrfach gesendet werden,
+ohne mehrfach ausgeführt zu werden.
+```
+
+### Filtering
+
+```text
+filter[status]=active
+filter[customer_id]=123
+```
+
+### Sorting
+
+```text
+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:
+
+```text
+Das System informiert andere Systeme automatisch,
+wenn ein Ereignis passiert.
+```
+
+## Nächster Schritt
+OpenAPI-Stub für V1 erstellen.