API-Kompatibilität und Updates

1) Grundprinzipien der Kompatibilität

Additiv-first: Neues hinzufügen, ohne das Alte zu brechen (neue optionale Felder/Endpunkte, neue Enum-Werte).
Stabile Verträge: „Was in der Spezifikation versprochen wird - das funktioniert“; Das Verhalten wird dokumentiert.
Backward> Forward: Priorität der Abwärtskompatibilität; Vorwärts ist über tolerant-readers erlaubt.
Die Dokumente sind primär: Die einzige Quelle der Wahrheit ist die Version des Schemas in der Registry (OpenAPI/AsyncAPI/Proto).
Klare Evolution: Breaking - nur durch eine neue Major-Version und einen Migrationsführer.

2) Taxonomie der Veränderung

2. 1 Kompatibel (MINOR/PATCH)

Optionale Felder/Header, neue Endpunkte, Query-Parameter mit Defaults hinzufügen.
Erhöhung der Limits ('page _ size', TTL), Klärung der Fehler ohne Änderung der Codes/Semantik.
Hinzufügen von enum-Werten, wenn Clients „unbekannt“ (tolerant-reader) ignorieren.

2. 2 Mehrdeutig (Behavioral)

Das Ändern von Standardwerten, Sortierreihenfolge, dünnen Timeouts, Quoten - kann die Geschäftslogik „brechen“. Erfordert RFC + Ankündigung und Kanarienvögel.

2. 3 Breaking (MAJOR)

Umbenennen/Löschen von Feldern, Ändern von Typ/Format, Ersetzen von Fehlercodes, Inkompatibilität von Verträgen/Authentifizierungsschemata.

3) Versionierungspolitik

Strategie: 'path versioning' ('/v1', '/v2').
Moll/Patch: „hinzufügen, nicht brechen“.
Datierte Überschriften (extra): 'X-API-Version-Date' für sanfte, schrittweise Änderungen.
Medientypen (Opz.) : `Accept: application/vnd. acme. v1 + json 'für feine Granulation.

4) Deprections und Sonnenuntergang

4. 1 Kommunikationsüberschriften

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 Reihenfolge der Ausgabe

1. Ankündigung im Portal/Newsletter/SDK Release Notes.
2. Das Warnfenster ≥ 90-180 Tage.
3. Status im adoption dashboard.
4. Nach Sonnenuntergang - 410 Gone oder „read-only“ -Modus für die Grace-Periode, wenn vereinbart.

5) Migrationen und gemeinsame Koexistenz von Versionen

Dual-write/dual-read in der Übergangszeit und Abstimmung mit Reports.
Adapter (temporär): Gateway-Konvertierung von alten Payload → neue Schemata; Die Lebensdauer des Adapters ist begrenzt.
SDK-Hilfe: Releases, die beide Versionen unterstützen, mit Deprection Warnings (1x pro Prozess).
Ficha-Flags: Aufnahme einer neuen Semantik durch eine Liste von Schlüsseln/Tenanten.

6) Backward und vorwärts Kompatibilität

6. 1 Backward (alte Clients ↔ neuer Server)

Keine Änderung der Typenformate/bindend.
Neue Felder sind nur optional.
Fehler - früher 'error _ code', neue Codes hinzufügen, nicht ersetzen.

6. 2 Forward (neue Clients ↔ alter Server)

Prüfen Sie über 'OPTIONS '/'/versions' auf Möglichkeiten (capabilities).
Grace-Verhalten: Der Kunde muss fehlende Fics tolerieren.

7) Verträge und automatische Prüfungen

Registry: Speichern Sie die Versionen der Schemata; PR-Difs → „Breaking/Non-Breaking“ -Berichte.
Linter: Namen/Typen, Idempotenz, Pagination, stabile Codes.
CDC (Consumer-Driven Contracts): Integratortests in der CI des Lieferanten (Pact und Analoga).
Gate: PR wird beim Breaking ohne' Major Bump '/RFC blockiert.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) Kanarienfreigabe und Rücklauf

Canary: 10% → 25% → 50% → 100% Traffic Auto-Rollback bei Verschlechterung des SLO (5xx/latency/429).
Beta-Schlüssel: Zugriff auf neue Versionen über allowlist.
Release freeze: Wenn ein error-budget verbrannt wird.
Akzeptanzanalyse: Traffic/Client-Anteil auf neuer Version, Migrationszeit.

9) Kompatibilität im Detail: Fehler, Pagination, Idempotenz

9. 1 Fehler

HTTP-Status in bestehenden Skripten nicht ändern.
„error _ code“ - stabil; neue Codes nur hinzufügen.
'application/problem + json' ist ein einheitliches Format.

9. 2 Pagination

Wechsel zu cursor/keyset = MINOR, wenn das alte' offset/limit 'unterstützt wird.
Dokumentieren Sie die Sortierung'(updated_at,id) 'und die Stabilität des Cursors.

9. 3 Idempotency

Für das Schreiben - "Idempotency-Key" + "409 IDEMP_REPLAY' im Konflikt.
Migrationen dürfen die Semantik der Idempotenz nicht verändern.

10) Gateway-Transformationen (wenn relevant)

Map v1→v2 Felder, normalisieren Fehler, konvertieren Datums-/Geldformate.
Guardrails: Transformationen sind transparent und protokolliert; Verstecken Sie das Breaking nicht, sondern verwenden Sie es als Brücke mit begrenzter Laufzeit.

11) Kommunikation und Portal

Changelog с датами (`added/changed/deprecated/removed/fixed`).
Versionskarte: Status (Beta/GA/deprecated), Sunset-Datum, Links zu Hydes.
Benachrichtigungen Webhooks: 'deprecation. notice`, `version. released`, `plan. change`.
SDK Release Notes + Banner im Portal.

12) Erfolgsmetriken

Adoption rate v2 (nach Anfragen/Kunden).
Backward-compat incidents (Anzahl der „Entlassungen“).
Fehler Mix (4xx/5xx/429 Anteile) vor/nach Release.
Time-to-Adopt ist der Median.
Stützlast (Tickets/Woche).
Cost-to-Serve (Infrastrukturkosten pro Anruf).

13) Vorlagen und Beispiele

13. 1 Überschriften von Versionen und Deprektionen

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 Versionsrichtlinie (YAML-Fragment)

yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]

13. 3 OpenAPI: kompatibles Hinzufügen eines Feldes

yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive

14) Release Checkliste (MINOR/MAJOR)

MINOR

• DIFF: non-breaking, linter green
• Dokumentation/SDKs aktualisiert (Beispiele/Codecs)
• Kanarienvogel + Auto-Rollback durch SLO
• Kommaplan, Seite im Portal
• Adoption Dashboards und Fehler

MAJOR

• RFC/ADR, Sunset-Datum und Fenster ≥90 -180 Tage
• v1↔v2 Bridge (Gateway) und Migrationsführer
• Dual-write/read und Abstimmungen
• SDKs mit beiden APIs + Warnungen
• Pilot mit Schlüsselintegratoren

15) Implementierungsplan (3 Iterationen)

1. Fundament (2 Wochen):

Registry-Schaltungen, Lint und Auto-Diff in CI; Kompatibilitätspolitik; die Überschriften „Deprecation/Sunset“.

2. Verwaltete Releases (3-4 Wochen):

Kanarienvögel, Ficha-Flaggen, SLO-Alerts; Versionsportal; SDK-Versionen mit Unterstützung für 2 Zweige.

3. Automatisierung und Skalierung (kontinuierlich):

CDC-Verbrauchertests in CI, Sunset-Prognose für Adoption-Trends, automatische Benachrichtigungen und Erinnerungen.

16) Mini-FAQ

Ist es möglich, den Feldtyp ohne Major zu ändern?
Nein. „stroka→chislo“ ist Breaking. Geben Sie ein neues Feld ein, das alte Feld deprecate.

Enum: Kann ich Werte hinzufügen?
Ja, wenn die Kunden tolerant-Leser sind. Ansonsten - Alarmierung und Beta zuerst.

Wie lange sollte man die alte Version behalten?
Während adoption ist eine neue ≥95% und ein deprection-Fenster gehalten. Fixieren Sie die Frist in der Politik.

Summe

API-Kompatibilität ist eine Disziplin: additive Herangehensweise, formale Schemata und Diphs, kanarische Releases, klare Deprections und verwaltete Migrationen. Verankern Sie Ihre Änderungspolitik, automatisieren Sie Inspektionen und Kommunikation, messen Sie adoption - und Ihre Updates werden die Kunden nicht mehr stören, und die Geschwindigkeit der Evolution wird steigen, ohne die Zuverlässigkeit zu verlieren.