# API Versionierung und Deprecation Policy

## Ziel

Diese Policy definiert eine reproduzierbare Versionierungsstrategie fuer `helpyourneighbour`, damit API-Clients stabil bleiben und Breaking Changes planbar sind.

## Versionierungsmodell

- Basispfad-Versionierung: `/v1/...`, `/v2/...`
- Aktueller Stand dieses Repos ist funktional `v1`.
- Fuer die laufende Migration gilt: bestehende Routen ohne Prefix bleiben bis zur vollstaendigen Umstellung als Legacy-Compat aktiv.

## Semantik

- **Minor Change (non-breaking):** neue optionale Felder, neue Endpunkte, neue optionale Query-Parameter.
- **Major Change (breaking):** Umbenennung/Entfernung von Feldern, strictere Validierung mit API-Break, geaenderte Fehlersemantik.
- Non-breaking Aenderungen bleiben innerhalb derselben Major API (`v1`).
- Breaking Aenderungen erzeugen eine neue Major API (`v2`).

## Deprecation-Regeln

Bei geplanter Entfernung eines Endpunkts/Felds:

1. Markierung als `deprecated: true` in OpenAPI.
2. Deprecation-Hinweis in Response-Headern:
   - `Deprecation: true`
   - `Sunset: <RFC-1123 Datum>`
   - optional `Link: <migrations-url>; rel=\"deprecation\"`
3. Changelog-Eintrag und Migrationshinweise im Repo (`docs/`).
4. Mindestfrist bis Removal: **90 Tage**.

## Kompatibilitaetsgarantien

- JSON-Felder werden nicht ohne neue Major API entfernt.
- Typen werden nicht stillschweigend geaendert.
- Neue Pflichtfelder werden nicht in bestehende Request-Bodies von `v1` eingefuehrt.

## Fehlerverhalten

- Fehlerobjekte folgen stabil dem Muster `{ "error": ... }`.
- Neue Fehlercodes werden additive eingefuehrt.
- Bereits genutzte HTTP-Statuscodes bleiben stabil, ausser bei neuer Major API.

## Rollout-Prozess fuer Breaking Changes

1. ADR erstellen (Design + Impact).
2. `v2` Endpunkt parallel einfuehren.
3. `v1` als deprecated markieren (Header + OpenAPI).
4. 90-Tage-Frist einhalten.
5. Nach Frist `v1` entfernen.

## Definition of Done fuer API-Aenderungen

- OpenAPI aktualisiert (`/openapi.yaml` und `docs/openapi.yaml`).
- Changelog/Migrationshinweis vorhanden.
- Contract-Tests fuer geaenderte Endpunkte aktualisiert.
- Breaking vs non-breaking explizit im PR beschrieben.