58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
|
# 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.
|