API-Versionsstrategien

Warum wir eine Versionierung brauchen

Die API ändert sich schneller als die Clients. Versionierung ermöglicht die Freigabe von Fiches und das Editieren von Fehlern ohne Integrationsbrüche, setzt ein Veränderungsritual und macht Evolution vorhersehbar. Der Schlüssel: additive Änderungen standardmäßig, Majors - nur für Brüche, automatische Kompatibilitätsprüfungen und eine durchdachte Sunset-Richtlinie.

Grundprinzipien

1. Additiv-first: neue optionale Felder/Methoden/Ereignisse - ca. Löschen und Bedeutungsänderung - Dur.
2. MGC (Mindestgarantievertrag) stabil; Anreicherung - durch capabilities/'? include ='.
3. Toleranter Leser: Kunden ignorieren unbekannte Felder und erleben enum Erweiterungen korrekt.
4. Semantic Versioning: `MAJOR. MINOR. PATCH ™ für Artefakte, SDKs und Events.
5. Automate: schema-diff, Linters und CDC-Tests blockieren Breaking-Änderungen.

Wo die Version zu speichern (Adressierungsmechanik)

REST/HTTP

URI-Version: '/v1/orders' → einfach zu routen, bequem in Gateways. Das Minus „verdeckt“ die Entwicklung der Vorstellungen.
Mediatyp/Titel: 'Accept: application/vnd. example. orders. v1 + json'- genaue Formatsteuerung; schwieriger zu debattieren.
Query-Version:'? api-version = 1'- praktisch für A/B, aber leicht in Caches/Logs zu verlieren.
Empfehlung: URI für Major-Linien + Feature/Capability-Flags und Content-Negacation für Minor-Erweiterungen.

gRPC / Protobuf

Pakete/Dienste: 'Paketzahlungen. v1; service PaymentsV1; 'sind explizite Linien.
Die Tag-Nummerierung ist unverändert; gelöschte Tags nicht erneut verwenden.
Neue Felder - 'optional'; breaking → eine neue „.v2“.

GraphQL

Schema ohne explizite Major in der URL. Evolution durch @ deprecated und Migrationsfenster; „real“ major ist das neue Endpoint-Schema.
Kontrolle complexity/depth ist Teil des Vertrages.

Event-driven (Kafka/NATS/Pulsar)

Name der Veranstaltung: 'payment. authorized. v1 'ist die Version im Typ.
Scheme Registry (Avro/JSON Schema/Protobuf) mit Kompatibilitätsmodi (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' und 'v2' für eine Übergangszeit.

Versionsmodell und Änderungsrichtlinie

Semantic Versioning

MAJOR - brechende Änderungen: Löschen/Umbenennen von Feldern, Ändern von Partitionierungsschlüsseln, andere Bedeutung von Status, Verschärfung der Validierung.
MINOR - additiv: neue optionale Felder/Endpunkte/Ereignisse, neue Enum-Werte bei tolerant-reader.
PATCH - Korrekturen ohne Änderung des Vertrages und der Semantik.

Deprecation & Sunset

Markieren Sie veraltet ('Deprecated: true','@ deprecated'), veröffentlichen Sie Sunset-Datum, Alternative und Migrationshyde.
In HTTP die Header 'Sunset', 'Deprecation'; in Veranstaltungen - separate' .deprecation. notice`.
Verwenden Sie Telemetrie, um eine Entscheidung über den Rückzug zu treffen.

Versionsstrategien nach Stil

REST

Hauptlinien auf/v1 ,/v2.
MINOR: Erweiterung der Schaltungen,'? fields =','? include ='; sichere enum-Erweiterungen.
ETag/If-Match und idempotente POSTs für Konsistenz ohne Bruch.
Fehler - stabiles Format ('type', 'code', 'trace _ id').

gRPC

Neue Dienste/Methoden für Brüche einführen: 'PaymentsV2. Capture`.
Fehlerstatus und Deadline-Semantik sind Vertragsbestandteil; Änderung → neue Methode/neuer Dienst.
Streaming: Vereinbaren Sie die Reihenfolge der Nachrichten und ändern Sie sie nicht in Moll.

GraphQL

Fügen Sie Felder und Typen frei hinzu; Löschungen - über'@ deprecated'+ Migrationsfenster; großes Redesign → neues Schema ('/graphql-v2').
Introspektion und Beschreibungen sind ein Muss für Kundenmigrationen.

Events

Core vs enriched: Der Core ist stabil, die Anreicherungen leben nebeneinander und werden separat versioniert.
Der Partitionierungsschlüssel ist innerhalb der Hauptlinie unverändert.
Major-Migrationen - 'dual-emit' + Migration von Projektionen/Consumern.

Negotiation und Capability-Flags

Capabilities: Der Client sendet 'X-Capabilities: risk_score,price_v2'; Der Server antwortet mit einer erweiterten Ansicht.
Prefer (HTTP) und „hints“ für partielle Antworten.
In Sockets/Streams eine Handshake-Nachricht mit einer Liste der unterstützten Erweiterungen.

Veröffentlichung von Major-Versionen ohne Schmerzen

1. RFC/ADR: Warum ein Major benötigt wird, was kaputt geht, die Risikomatrix.
2. Dual-Run: parallele Ausführung von 'v1' und 'v2' (doppelte Veröffentlichung von Ereignissen, zwei Gateway-Routs, Verkehrsspiegelung).
3. Migrations-Adapter: Proxy/Übersetzer „v1↔v2“ für schwere Clients.
4. Canary: nach Kundengruppen/Äpfeln/Tags im Gateway.
5. Sunset-Plan: Termine, Kommunikation, Stände, Testdaten, Nutzungsüberwachung.

Plattform- und Infrastrukturrollen

API Gateway/Service Mesh: Routing nach Version, Header, Pfad; rate-limit и auth per-version.
Schema Registry & Catalog: Quelle der Wahrheit für Specs/Schemas mit Diffusgeschichte.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observability: Die Version muss in den Logs/Traces/Metriken landen.

Versionstests

Schema-diff in PR: Breaking blockieren.
Consumer-Driven Contracts: Der Anbieter wird gegen Verträge von echten Verbrauchern geprüft.
Goldene Proben: Referenzantworten auf Versionen.
E2E-Kanarienvogel: Vergleich von p95/p99, Fehlern und Timeouts zwischen den Versionen.
Replay für Ereignisse: Projektionen werden ohne Diskrepanzen auf v2 zurückkompiliert.

Daten- und Datenbankmigration

Für REST/gRPC: DB-Migrationen werden durch Expand-and-Contract koordiniert (fügen Sie eine Spalte hinzu → beginnen Sie zu schreiben → wechseln Sie das Lesen → entfernen Sie das Alte).
Für Events: Dual-Emit und Consumer Migration; manchmal - das wiederholte Abspielen des Protokolls auf neue Projektionen.
Machen Sie keine „großen Explosionen“ - brechen Sie in Schritte mit Rollbacks.

Beziehung zur Sicherheit

Scopes pro Version: separate OIDC-Scopes/Rollen für v1/v2.
Token Secrets/Claim's sind Teil des Vertrages; ihr Wechsel = major.
PII/PCI - Erweitern Sie payload nicht unnötig; neue Felder - mit einem Minimum an Privilegien.

Antimuster

Swagger-wash: Spezifikation aktualisiert, Server nicht (oder umgekehrt).
Die Überverwendung von Protobuf-Tags ist ein leiser Datenverderb.
Ein Wechsel von Enum-Bedeutungen ohne Major.
Global '/v2'„aus Gründen der Kosmetik“: eine Version ohne die Tatsache des Abbruchs.
Sunset/Usage-Metriken vergessen: Es ist nicht möglich, die alte Version sicher zu entfernen.
Ein gemeinsames Top für verschiedene Majors: das Mischen von Ordnungen und Schlüsseln.

Checkliste vor der Veröffentlichung

• Die Änderungen sind additiv oder eine separate Hauptlinie ist vorbereitet.
• Linters und schema-diff grün (breaking nicht geklettert).
• Aktualisierte SDKs/Beispiele/Dokumentation, Fußnoten zur Kompatibilität.
• Toleranter Reader in Clients aktiviert; enum-fallback getestet.
• Für Major - Dual-Run-Plan, Adapter, Kanarienvogel, Sunset-Dates und Mailing.
• Metriken/Logs/Traces enthalten die Version und die Segmentierung nach dieser.
• Es gibt einen stand und golden-kits zu vergleichen v1↔v2.
• Bei Ereignissen - Schemaregister im BACKWARD/FULL-Modus, Partitionierungsschlüssel unverändert.

Beispielvorlagen

REST (URI + negotiation)

Route: '/api/v2/orders/{ id} '

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2'(Kernel) und 'payment. enriched. v2'(Teile).
Für die Übergangszeit kommen 'v1' und 'v2' vom Produzenten.

FAQ

Wann genau brauchen Sie '/v2'?
Wenn sich Invarianten/Semantik ändern, werden Felder/Methoden entfernt, das ID-Format, der Partitionierungsschlüssel, SLAs/Timings werden geändert, so dass Clients brechen.

Kann ich ohne explizite Version in REST leben?
Nur für kleine Systeme. Für externe Integrationen sind explizite Hauptlinien besser.

Wie lange dauert es, eine veraltete Version zu behalten?
Abhängig vom Ökosystem. Für externe Partner in der Regel 6-12 Monate mit Frühwarn- und Kanarienvogel.

Wie unterscheidet sich die Ereignisversion von der API?
Ereignisse - nur Append; neue Semantik = neuer Typ '.v2' und dual-emit. Der Partitionierungsschlüssel ist Teil des Vertrags.

Ergebnis

Versionierungsstrategien sind ein Prozess und Werkzeuge: Standard-additive Evolution, klare Hauptlinien, Capability-Negotiation, Dual-Run und Sunset. Hinzu kommen automatische Kompatibilitätsprüfungen, Nutzungstelemetrie und Dokumentationsdisziplin - und Ihre APIs werden sich schnell entwickeln, ohne „nächtliche Migrationen“ und unerwartete Stürze bei den Kunden.