API-Versionierung: ein Ablauf für inkompatible Änderungen

Planen Sie API-Änderungen mit Client-Inventar, Kompatibilitätsprüfung, Migrationsbelegen, Abkündigung und einer kontrollierten Release-Reihenfolge.

Ein zentraler Integrationsknoten verbindet getrennte Systeme über silberne Kanäle.

Eine API-Änderung ist nur im Verhältnis zu ihren Clients sicher. Eine neue Routenversion beendet keine Migration, und ein zusätzliches Feld ist nicht für jeden Verbraucher folgenlos. Erfassen Sie Anwendungen, Integrationen und Hintergrundjobs mit Eigentümern und Aktualisierungsmöglichkeiten. Mobile Apps und externe Partner können lange nach dem Server-Release noch älteres Verhalten verwenden. Diese Realität muss die Übergangsplanung bestimmen.

Die tatsächliche Vertragsänderung einordnen

Prüfen Sie Anfragefelder, Antwortform, Statuscodes, Fehlerbedeutung, Rechte, Standardwerte, Seitennavigation und Sortierung. Eine geänderte Bedeutung kann Geschäftslogik brechen, obwohl JSON unverändert bleibt. Ein neuer Enum-Wert kann einen Client treffen, der eine geschlossene Liste voraussetzt. Schema-Vergleiche helfen, ersetzen aber keine repräsentativen Client-Prüfungen. Dokumentieren Sie, ob eine Änderung kompatibel, bedingt kompatibel oder migrationspflichtig ist. Halten Sie besonders fest, welche Annahmen nicht direkt aus der technischen Spezifikation hervorgehen.

Den Übergang entwerfen

Führen Sie neues Verhalten möglichst neben dem alten Vertrag ein. Ändern Sie Speicherung schrittweise, damit beide Versionen während der Übergangszeit funktionieren. Setzen Sie keine gleichzeitige Aktualisierung aller Clients voraus. Definieren Sie Versionskennzeichnung und einheitliche Beispiele. Übersetzt ein Adapter alte Anfragen, prüfen Sie dessen Geschäftssemantik statt nur Feldnamen. Benennen Sie Verantwortung und belegbare Abschaltbedingungen für die Kompatibilitätsschicht. Zusätzlicher Übergangscode braucht ebenfalls Monitoring und Pflege, solange echte Verbraucher davon abhängen.

Eine Migrationscheckliste aufbauen

Veröffentlichen Sie geänderten Vertrag, praktische Vorher-Nachher-Beispiele und Zeitplan im vereinbarten Kanal.
Testen Sie wichtige Verbraucher mit realistischen Anfragen und Fehlerfällen gegen das neue Verhalten.
Messen Sie verbleibende Alt-Nutzung ohne unnötige sensible Nutzdaten zu protokollieren.
Planen Sie Rückkehr oder Vorwärtsreparatur für Datenänderungen und kennzeichnen Sie irreversible Grenzen.

Nach Belegen abschalten

Gleichen Sie beobachteten Verkehr mit dem Client-Inventar ab. Kurze Inaktivität beweist nicht, dass ein monatlicher Job ungenutzt ist. Kontaktieren Sie Eigentümer ungeklärter Verbraucher und dokumentieren Sie akzeptierte Ausnahmen. Beobachten Sie nach der Abschaltung Fehler und Supportmeldungen der betroffenen Vorgänge. Das Ergebnis ist nicht nur eine aufgeräumte Spezifikation, sondern eine bekannte Menge von Verbrauchern auf einem unterstützten Vertrag. Alter Code und Dokumentation verschwinden erst, wenn ihre tatsächlichen Abhängigkeiten aufgelöst sind. Kennzeichnen Sie außerdem Dokumentationsbeispiele mit der unterstützten Version. Veraltete Beispielanfragen können neue Verbraucher versehentlich auf einen bereits auslaufenden Vertrag bringen. Eine technisch erfolgreiche Migration braucht deshalb auch eine bereinigte Einstiegsdokumentation und eindeutige Hinweise für neue Integrationspartner.

Häufige Fragen

Gehört die Version in URL oder Header?

Beides kann funktionieren. Wählen Sie eine eindeutige Konvention für Clients, Infrastruktur und Dokumentation.

Ist ein zusätzliches Feld immer sicher?

Nein. Strenge Parser oder Geschäftsannahmen können trotzdem scheitern; prüfen Sie reale Verbraucher.

Wie lange sollte die Abkündigung dauern?

Berücksichtigen Sie Release-Zyklen, Verpflichtungen und Migrationsaufwand und kommunizieren Sie den Zeitraum klar.

Ersetzen Schema-Vergleiche Client-Tests?

Nein. Semantik, Berechtigungen und Geschäftsannahmen werden damit nicht vollständig geprüft.

Wann darf die alte Version weg?

Wenn Eigentümer und Nutzungsbelege die Abschaltung tragen, einschließlich seltener Jobs und vereinbarter Ausnahmen.

Vom Vorhaben zu einem umsetzbaren Umfang

Teilen Sie Nutzerablauf, Schnittstellen und Rahmenbedingungen. Gemeinsam klären wir den Umfang und erstellen eine Schätzung mit Annahmen und Ausschlüssen.

Leistungsumfang ansehen →