Mit API-Änderungen umgehen
Eine Integration ist nicht beim Go-live fertig; sie ist fertig, wenn sie stillgelegt wird. So verändert sich die Plattform unter ihr, und das hat Ihre Seite damit zu tun.
Eine Version, und sie ändert sich additiv
Es gibt eine aktuelle Version, /v1, und jeder Pfad lebt darunter.
Innerhalb einer Version sind Änderungen additiv:
| Additiv — passiert ohne Ankündigung | Brechend — passiert nie innerhalb einer Version |
|---|---|
| Eine neue Ressource erscheint | Ein Feld wird entfernt |
| Ein neues optionales Feld erscheint in einer Antwort | Ein Feld ändert den Typ |
| Ein neuer optionaler Parameter wird akzeptiert | Ein Pflichtparameter kommt hinzu |
| Ein neuer Wert erscheint in einem Aufzählungsfeld | Eine Ressource oder ein Endpoint wird entfernt |
| Ein neues Event-Topic erscheint | Die Bedeutung eines bestehenden Felds ändert sich |
Dieser Vertrag ist nur etwas wert, wenn Ihre Seite ihre Hälfte hält, und die besteht aus einer Regel:
Dasselbe gilt für Aufzählungswerte. Ein neuer Bestellstatus, eine neue Listenart oder ein neues Event-Topic ist additiv; Code, der erschöpfend switcht und im Default-Fall wirft, ist Code, der werfen wird.
Wo Änderungen angekündigt werden
Vier Kanäle feuern zusammen, es gibt also keinen einzelnen Ausfallpunkt beim Erfahren:
| Kanal | Was er trägt | Wer ihn beobachten sollte |
|---|---|---|
| Der Changelog | Jede Änderung, gruppiert als added / changed / deprecated / fixed / removed. Per E-Mail und RSS verfügbar | Der Integrationsverantwortliche, und jeder Integrator |
| Das Developer Portal auf revenexx.dev | Migrationsleitfäden, veröffentlicht, bevor eine brechende Änderung ausgeliefert wird | Wer die Arbeit machen wird |
| Antwort-Header | Ein Signal auf den Aufrufen selbst, sobald etwas abgekündigt ist | Ihr Monitoring |
| Direkte E-Mail | An registrierte Integrationskontakte gesendet | Wen Sie registriert haben |
Die letzte Zeile lohnt es, heute anzugehen: Stellen Sie sicher, dass der registrierte Kontakt jeder Integration eine Team-Adresse ist, kein Entwickler, der 2026 gegangen ist. Das ist die Nachricht, die Sie persönlich erreicht, wenn etwas zu brechen droht.
Der Abkündigungs-Lebenszyklus
Nichts verschwindet ohne Vorwarnung. Wird eine Version oder ein Endpoint ausgemustert, durchläuft er vier Stufen:
| Stufe | Was sie bedeutet | Dauer | Was Sie tun |
|---|---|---|---|
| Current | Voll unterstützt | — | Nichts |
| Deprecated | Funktioniert noch. Ein Ersatz existiert, der Migrationsleitfaden ist veröffentlicht | Mindestens vier Wochen | Die Arbeit planen und terminieren |
| Sunset | Funktioniert noch, aber Sie sind über den vorgesehenen Umstieg hinaus | Ein kurzes letztes Fenster | Jetzt migrieren |
| Removed | Weg. Aufrufe schlagen fehl | — | Zu spät |
Solange etwas abgekündigt ist, tragen die Antworten darauf ein Signal — eine Abkündigungsmarkierung und das Datum, an dem es verschwinden soll. Zwei Dinge tun Sie damit:
Protokollieren. Eine Integration, die drei Monate lang leise gegen einen abgekündigten Endpoint weiterarbeitet, ist eine, die stehen bleibt, ohne dass jemand die Warnungen bemerkt hat.
Alarmieren. Behandeln Sie das erste Auftauchen eines Abkündigungssignals als Ereignis, für das es sich lohnt, jemanden zum Lesen zu wecken — nicht um es in dieser Nacht zu beheben, sondern um es zu terminieren. Vier Wochen reichen, wenn Sie am ersten Tag anfangen, und reichen nicht, wenn Sie in Woche drei anfangen.
Event-Topics versionieren anders
Das sollten Sie wissen, weil es Leute kalt erwischt: Eine brechende
Änderung an einem Event-Payload ändert das bestehende Topic nicht. Sie
kommt als neues Topic mit Versionssuffix — aus order.created wird
order.created.v2 —, und beide laufen eine Weile parallel.
Das heißt: Ihr Empfänger arbeitet unverändert auf dem alten Topic weiter. Es
heißt auch: Sie müssen das neue aktiv abonnieren, um die neue Form zu
bekommen, und niemand tut das für Sie. Taucht ein .v2-Topic in
Events › Event Catalog auf, ist das Ihre Ankündigung.
Die nächste Version testen
Der Sinn einer Sandbox ist, dass das nicht beängstigend ist.
- Den Migrationsleitfaden lesen und markieren, welche Ihrer Integrationen tatsächlich betroffen sind. Meist ist es eine, nicht alle.
- Die Sandbox-Integration auf das neue Verhalten zeigen lassen und Ihre Fixture-Tests fahren — dieselben Idempotenz-, Replay- und Timeout-Tests wie beim Go-live.
- Das echte Volumen einmal fahren. Migrationsänderungen ändern manchmal die Performance mit, nicht nur die Form.
- Während des Abkündigungsfensters nach Produktion ausrollen, nicht im Sunset-Fenster.
- Eine Woche die Protokolle beobachten, bevor Sie es als erledigt betrachten.
Ist die Sandbox von der Produktion weggedriftet, frischen Sie sie vor dem Start auf — eine gegen einen veralteten Tenant getestete Migration ist eine ungetestete Migration. Siehe Eine Sandbox einrichten.
Ein Änderungsregister, das sich zu führen lohnt
Eine Tabelle, eine Seite, quartalsweise durchgesehen. Sie beantwortet die einzige Frage, die zählt, wenn eine Abkündigungsnotiz eintrifft: Betrifft uns das, und wer macht die Arbeit?
| Spalte | Beispiel |
|---|---|
| Integration | ERP order sync |
| Verantwortlich (ein Team, keine Person) | IT Systems |
| Genutzte Ressourcen und Topics | /orders, orders/{id}/acknowledge, order.created |
| Schlüssel | erp-order-sync-prod |
| Zuletzt geprüft | 2027-03 |
| Notizen | Konsumiert auch den nächtlichen Preisexport |
Fünfzehn Minuten zu bauen, und jede künftige Abkündigungsnotiz wird von einer Untersuchung zu einem Nachschlagen.
Was Sie prüfen, quartalsweise
- Jede Integration im Register existiert noch, und alles, was existiert, steht im Register.
- Der registrierte Kontakt jeder Integration ist eine Team-Adresse, die jemand liest.
- Keine Integration ruft etwas auf, das als deprecated markiert ist.
- Jemand hat seit dem letzten Review den Changelog gelesen.
Weiter
- Integrationen überwachen — wo das Abkündigungssignal auftaucht.
- Eine Integration durchgängig testen — die Tests, die bei jeder Migration erneut laufen.