helpyourneighbour/docs/api-versioning.md

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.