# 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.