92 lines
1.4 KiB
Markdown
92 lines
1.4 KiB
Markdown
# 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.
|