Definieren Sie, was der öffentliche Vertrag ist, ergänzen Sie neue optionale Möglichkeiten abwärtskompatibel, ändern Sie die Bedeutung bestehender Felder nicht stillschweigend und erstellen Sie bei einer inkompatiblen Änderung eine klare Version mit Migrationsanleitung, Supportzeitraum, Vertragstests und Monitoring der aktiven Clients.
API-Versionierung löst die Situation, in der sich die Bedürfnisse des Anbieters und der Clients in unterschiedlichem Tempo entwickeln. Die Änderung eines Feldnamens, der Bedeutung eines Status oder einer Pflichtangabe kann eine Integration beschädigen, selbst wenn der Endpoint weiterhin antwortet. Ohne klare Richtlinie scheut sich das Team, den Vertrag zu verbessern, oder überrascht umgekehrt die Clients regelmäßig mit inkompatiblen Änderungen.
Die beste neue Version ist oft diejenige, die gar nicht erstellt werden muss, weil sich die Änderung kompatibel ergänzen lässt. Wenn eine Inkompatibilität sinnvoll ist, braucht sie eine Übergangsfrist, Dokumentation, eine Testumgebung und Kenntnis der aktiven Konsumenten. Eine Version ist nicht nur eine Nummer in der URL; sie umfasst Schema, Verhalten, Fehler und betriebliche Erwartungen.
Definieren Sie Vertrag und Kompatibilität
Der Vertrag umfasst Pfade, Methoden, Felder, Typen, Pflichtangaben, Enums, Statuscodes, Reihenfolge und Bedeutung der Operationen. In der Praxis gehören auch Limits, Paginierung, Authentifizierung und zeitliches Verhalten dazu. Eine Änderung des internen Codes ist keine API-Änderung, solange sie die beobachtbare Erwartung des Clients nicht verändert. Halten Sie diesen Umfang schriftlich fest und pflegen Sie ihn an einer einzigen maßgeblichen Stelle.
Abwärtskompatibilität bedeutet, dass ein bestehender, korrekt geschriebener Client ohne erzwungene Änderung weiter funktioniert. Das Hinzufügen eines optionalen Feldes ist meist nur dann kompatibel, wenn der Client unbekannte Werte gemäß Kontrakt toleriert. Ein neuer Enum-Wert kann einen geschlossenen Switch zum Absturz bringen. Beurteilen Sie das tatsächliche Verhalten, nicht nur das syntaktische Schema.
Bevorzugen Sie eine kompatible Weiterentwicklung
Fügen Sie das neue Feld zunächst als optionales Feld hinzu, befüllen Sie es und ermöglichen Sie den Clients die Umstellung. Behalten Sie das alte Feld während des vereinbarten Zeitraums bei und überwachen Sie dessen Nutzung. Ändern Sie weder Einheit, Zeitzone noch Bedeutung ohne neuen Namen oder neue Version. Der Server sollte unwesentliche Erweiterungen einer Anfrage in vernünftigem Maß tolerieren, sofern die Sicherheit dies zulässt.
Erwägen Sie bei einer Verhaltensänderung eine neue explizite Fähigkeit oder einen Parameter statt eines versteckten Umschalters. Der Standardwert muss die Erwartungen bestehender Clients wahren. Eine vorübergehende doppelte Implementierung erhöht den Wartungsaufwand und braucht daher eine verantwortliche Person und ein Entfernungsdatum. Kompatibilität ist kein Grund, ohne Plan alles für immer beizubehalten.
- optionales Hinzufügen vor dem Entfernen
- neuer Name bei Bedeutungsänderung
- sicherer Standardwert
- überwachter Übergang mit Enddatum
Führen Sie die Version an einer geeigneten Grenze ein
Die Version kann in der URL, im Header, im Ereignisschema oder über einen anderen unterstützten Mechanismus ausgedrückt werden. Wählen Sie einen konsistenten Ansatz entsprechend der Plattform und der Art der Verteilung. Führen Sie nicht für jede Kleinigkeit eine neue Hauptversion ein. Sie sollte eine Reihe inkompatibler Erwartungen repräsentieren, die der Client bewusst wählen und testen kann.
Webhooks und Batch-Exporte benötigen eine eigene Payload-Version, auch wenn sie dieselben Domänenbegriffe wie die REST-API verwenden. Speichern Sie die Version mit dem Ereignis, damit der Empfänger es auch später verarbeiten kann. Die Dokumentation beschreibt Unterschiede, Migrationsbeispiele und bekannte Einschränkungen. Alte und neue Beispiele dürfen nicht ohne Kennzeichnung vermischt werden.
Kündigen Sie Deprecations an und unterstützen Sie die Migration
Ermitteln Sie vor der Abschaltung die aktiven Clients und die Kontakte ihrer Verantwortlichen. Die Ankündigung sollte den Grund, den Ersatz, die Unterschiede, Testmöglichkeiten, Termine und den Support-Kanal nennen. Ein einzelner Hinweis im Changelog reicht bei einem kritischen Partner nicht aus. Legen Sie die Übergangsfrist nach Risiko und Verträgen fest, nicht nach der Bequemlichkeit eines einzelnen Teams.
Stellen Sie eine Migrationsanleitung und Testszenarien bereit. Wenn sich eine veraltete Nutzung automatisch erkennen lässt, zeigen Sie im Portal oder in der Antwort eine Warnung an, ohne Informationen preiszugeben. Prüfen Sie vor der Abschaltung den Rückgang der Aktivität und eskalieren Sie unbekannte Konsumenten. Entfernen Sie den alten Code nach Ablauf der Frist kontrolliert und beobachten Sie unerwartete Fehler.
Automatisieren Sie Vertragstests und Beobachtbarkeit
Validieren Sie das Schema in der CI und vergleichen Sie es mit der zuletzt veröffentlichten Version. Provider-Tests prüfen Beispiele und Regeln, Consumer-Contracts erfassen wichtige Erwartungen realer Clients. Betrachten Sie sie nicht als vollständigen Ersatz für Integrationstests; die Bedeutung der Daten und betriebliche Limits erfordern End-to-End-Szenarien in einer sicheren Umgebung.
Überwachen Sie in der Produktion Version, Client, Validierungsfehler und die Nutzung veralteter Felder, ohne übermäßiges Profiling. Rollen Sie Änderungen schrittweise aus und bereiten Sie einen Rollback vor. Jeder Vorfall führt zu einer Aktualisierung von Richtlinien und Tests. Gut gesteuerte Versionierung ermöglicht es einer API zu wachsen, ohne dass jede Verbesserung zu einem koordinierten Ausfall wird.
- automatischer Abgleich des öffentlichen Schemas zwischen Releases
- Consumer-Erwartungen kritischer Integrationspartner
- Kompatibilitätstest mit historischen Beispielanfragen
- Monitoring von Clients, die die alte Version nutzen
- Überprüfung der Migrationsanleitung in der Testumgebung
- klarer Verantwortlicher für den Abschalttermin der alten Version
- kontrolliertes Entfernen von ungenutztem Kompatibilitätscode
Häufige Fragen
Muss die API-Version in der URL stehen?
Nein. Sie kann in der URL, im Header oder in einem anderen vereinbarten Mechanismus stehen. Wichtig sind Konsistenz, eine klare Wahlmöglichkeit für den Client, Dokumentation und die Fähigkeit, den Übergang im Betrieb zu bewältigen.
Ist das Hinzufügen eines neuen Feldes immer kompatibel?
Nicht immer. Ein Client kann unbekannte Felder oder neue Enums ablehnen. Der Vertrag muss die Toleranz festlegen, und die Änderung sollte durch Tests und anhand des Verhaltens aktiver Konsumenten überprüft werden.
Wie lange sollte die alte Version unterstützt werden?
Je nach Verträgen, Anzahl der Clients, Risiko und Aufwand der Migration. Legen Sie einen konkreten Plan fest, kommunizieren Sie ihn im Voraus und überprüfen Sie die Nutzung; zeitlich unbegrenzter Support bremst die sichere Wartung dauerhaft.
Quellen und weiterführende Lektüre
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
