Technologie und Infrastruktur → API-Versionierung

API-Versionierung

1) Warum es notwendig ist

• reduziert das Risiko von Incidents bei Releases,
• ermöglicht geplante Verbesserungen und Sicherheit,
• gibt Unternehmen einen vorhersehbaren Zeitpunkt für Partner-Migrationen.

2) Klassifizierung von Änderungen

PATCH (nicht brechend): Korrekturen ohne Vertragsänderung (Hinzufügen von optionalen Feldern, Validierungsfixes).
MINOR (erweiterbar): back-kompatible Erweiterungen (neue Endpunkte, Felder mit default).
MAJOR (breaking): Struktur, Semantik ändern oder Felder/Endpunkte löschen.

Empfohlen von SemVer 'MAJOR. MINOR. PATCH 'für Artefakte (SDKs/Schemas), wobei die „externe“ API-Nummer vereinfacht werden kann (v1, v2).

3) REST-Versionsmodelle

1. IM URI:

`GET /v1/payments/{id}`

Vorteile: transparent, cachefähig, leicht zu routen. Nachteile: doppelte Dokumentation, schwieriger subtil zu entwickeln.

2. In den Überschriften (Content Negotiation):

`Accept: application/vnd. company. payments. v2+json`

Vorteile: Flexibilität, kein „Müll“ in der URL, bequeme Entwicklung des Mediatyps. Nachteile: Es ist schwieriger, im Browser zu debatten, Sie brauchen einen disziplinierten Client.

3. In der benutzerdefinierten Überschrift:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Vorteile: nur an der Schleuse. Nachteile: kein Standard, Vorsicht mit Cache.

4. Version-Datum (datumsbasiert):

Gut für Fintech/Reporting: vorhersehbare „Schnitte“ von Veränderungen (z.B. vierteljährlich).

5. Versionierung der Ressource/des Modells:

Empfehlung: für externe Integrationen - 'URI vN' + Deprecation/Sunset Header; für intern - Sie können 'Accept' oder einen Versionsheader verwenden, wenn das Gateway und die Plattform dies unterstützen.

4) GraphQL

Bevorzugt werden keine globalen Versionen. Evolution durch Hinzufügen von Feldern/Typen und Deprivation ('@ deprecated (Grund: „“...)').
Brechende Veränderungen gibt es nur in „großen“ Fenstern (versionierter Schema-Namespace) mit Migrationshaid.
Achten Sie auf „n + 1“ und darauf, dass Sie die Bedeutung der vorhandenen Felder nicht ändern.

5) gRPC / Protobuf

Die Feldnummern sind unveränderlich. Markieren Sie gelöschte Felder als „reserviert“.
Fügen Sie Felder als optional mit sicheren Standard.
Verwenden Sie buf breaking/lint, um die Kompatibilität automatisch zu überprüfen.
Versionieren Sie Pakete/Module: 'Paketzahlungen. v1;` → `payments. v2`.

6) Ereignis-APIs (EDA)

Das Schema der Veranstaltung ist der gleiche Vertrag. Speichern Sie es in Schema Registry (Avro/JSON-Schema/Protobuf).
Topics und Versionen: 'Zahlungen. v1. authorized`, `payments. v2. authorized`.
Brechende Änderungen sind eine neue Art von Ereignis oder ein neues Oberteil.
Evolutionsgarantien: backward-kompatibel für Consumer während des LTS-Zeitraums.

7) Deprickationspolitik und EOL

• Deprecation: Labels in changelog und in Spezifikationen (OpenAPI/GraphQL SDL), Header
• „Deprecation: true“ und wann immer möglich „Sunset: Di, 31 Mär 2026 00:00:00 GMT“.
• Kommunikation: E-Mail/Partner-Portal, Webhooks-Benachrichtigungen, Release Notes.
• Zeitrahmen: MINOR - 3-6 Monate Unterstützung, MAJOR - 9-18 Monate (abhängig von der Kritikalität).
• Zeitfenster: In der „API-Versionsrichtlinie“ festlegen.

8) Routing und Freigaben

Gateway API (Kong/Apigee/Nginx/Envoy): Regeln nach Präfix '/v1/', nach Titel oder Mediatyp.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: Rollt die neue Version auf 1-5% des Traffics, vergleicht Metriken und Protokolle von Vertragsfehlern.
Feature Flags: Wir verstecken das Verhalten, ohne den Vertrag zu ändern.
Zero-Downtime der Migration: Stellen Sie bei MAJOR ein doppeltes Schreiben/Lesen (dual-write/read) des Datenschemas sicher.

9) Vertragsprüfung und Kompatibilitätskontrolle

OpenAPI Diff (oder swagger-diff) - Stellen Sie sicher, dass MINOR/PATCH die Schaltkreise nicht brechen.
Spectral Linting - Stil, erforderliche Metadaten (Version, Deprecation).
Consumer-Driven Contracts (Pact) - sorgt dafür, dass der Anbieter Kunden nicht kaputt macht.
buf breaking для protobuf.
Der CI sollte bei Bruchänderungen fallen, ohne den MAJOR zu erhöhen.

10) Dokumentation und SDK

Versionieren Sie die Specs: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
Generieren Sie SDKs nach Version (npm/maven/pypi) mit SemVer und changelog.
Markieren Sie veraltete Methoden im SDK mit Anmerkungen/Deprecated.

11) Observability nach Version

• RPS/Latenz/Fehler pro Version ('api _ version' Label).
• Endpoint-Nutzungskarten: Wer ist noch auf v1?
• Alerts: „> 10% 4xx due to contract mismatch“, „Altkunden> X% nach T-Datum“.

12) Caching und Versionen

Die On-Path-Version verbessert die Cachefähigkeit des CDN.

• `Vary: Accept, X-API-Version`.
• Ändern Sie nicht die Semantik der Antwort in MINOR, um die Cache-Schlüssel zu brechen.

13) Sicherheit

Verschlüsseln oder hacken Sie keine Version in JWT - die Version bestimmt die Anforderung, nicht das Token.
Legen Sie keine internen Baugruppennummern offen. Verwenden Sie in externen Nachrichten „v1/v2“.
Überprüfen Sie bei MAJOR die Validierung, Limits und die PII-Maskierung.

14) Migrationen und Auto-Assistenten

Veröffentlichen Sie „Migration Guide v1 → v2“: Tabelle der Feldübereinstimmungen, Beispiele für Anfragen/Antworten, Edge-Cases.
Bieten Client Linters (CLIs) an, die veraltete Felder hervorheben.
Für große Partner - Sandbox mit zwei Versionen und Testdataset.

15) Anti-Muster

„Eternal v1“: Fehlen von Terminen und Nutzungsmetriken.
Ausgeblendete brechende Änderungen in MINOR/PATCH.
„Version in query string“ ('? v = 2') - bricht den Cache und die Lesbarkeit.
„Ein Endpunkt - hundert Flaggenwerte“: schwer zu testen/zu dokumentieren.

16) Checkliste Umsetzung

1. Modell (URI/Accept/Header) für externe und interne Kunden ausgewählt.
2. SemVer für Spezifikationen und SDK, automatischer Breaking-Check im CI.
3. Deprecation/Sunset Kommunikationsrichtlinien und Vorlagen.
4. Gateway-Routing + Kanarienvögel, Dashboards nach Version.
5. CDC/Vertragstests zu kritischen Integrationen (Zahlungen, KYC, Reporting).
6. Die Dokumentation/SDK/Migrationsführer wird zeitgleich mit der Veröffentlichung veröffentlicht.
7. EOL-Plan mit Terminen und Verantwortlichen.

17) Beispiele

17. 1 REST (URI + Überschriften)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Content Negotiation (Mediatyp)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (Feldentzug)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Veranstaltungsmodell

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed'(neues Ereignis mit erweitertem Schema)

Schemas werden in Registry gespeichert, der Produzent veröffentlicht keine Ereignisse mit einem Schema, das die Kompatibilität verletzt.

18) Kontext iGaming/Fintech (Praxis)

Zahlungen: Eingabe v2 für neue PSPs, wobei 'status '/' decline _ reason' erweitert wird; auf dem Gateway Mupping v1 → v2 für die Berichterstattung.
KYC: MINOR fügt das Feld 'pep _ screening' hinzu, v1-Clients ignorieren, v2 erfordert.
Verantwortungsvolle Spiele/Limits: MAJOR ändert das Limitmodell (Tagegeld/Woche). Doppelexporte in die Berichterstattung vor EOL v1.
Berichterstattung an die Regulierungsbehörden: feste Versionen-Daten: 'reporting-2025-01'.

19) Mini-Politik (Beispiel für Wiki)

Modell: für externe APIs - „URI/vN/“; für intern - „Accept:... vN + json“ oder „X-API-Version: N“.
SemVer: Spezifikationen und SDKs werden als' N. minor. patch`. MAJOR erfordert RFC/ADR.
Kompatibilität: MINOR/PATCH - keine brechenden Änderungen. Break → nur durch MAJOR.
Deprecation/EOL: Ankündigung ≥90 Tage im Voraus Sunset-Datum in Kopfzeilen; LTS-Filiale für kritische Kunden.
Steuerung: OpenAPI diff/buf breaking in CI, CDC für wichtige Integrationen.
Observability: Metriken/Logs mit dem Label 'api _ version'.
Releases: Canary 5% ≥ 24h, dann schrittweise bis zu 100% mit grünen Metriken.

Ergebnis

Beim Versionieren geht es nicht um „/v2 in URL “, sondern um den Prozess: explizite Evolutionsregeln, automatische Kompatibilitätsprüfungen, verwaltete Releases und Respekt vor Integrationen. Geben Sie eine verständliche Richtlinie ein, automatisieren Sie Kontrolle und Beobachtbarkeit - und Änderungen sind keine Bedrohung mehr für das Produkt.