Eine API-Version wechseln, ohne den Datenfluss zu übersehen

Planen Sie den Wechsel einer Programmierschnittstelle (API) entlang der betroffenen Datenflüsse. Der neue Endpunkt ist nur ein Teil der Umstellung: Auch Felder, Berechtigungen und die Auswertung von Antworten müssen zum aufrufenden System passen.

Die betroffenen Aufrufer erfassen

Im fiktiven Unternehmen senden Kundenportal und Nachtimport Aufträge an dieselbe API. Nur das Portal umzustellen würde den zweiten Aufrufer zurücklassen. Halten Sie für jeden Aufrufer fest, welche Funktionen er nutzt und wer seine Umstellung durchführen kann. Nutzen Sie die Änderungs- und Abschaltinformationen des tatsächlichen Anbieters; aus einer Versionsnummer folgt keine allgemeingültige Migrationsfrist.

Google AIP-180 unterscheidet Kompatibilität von Quellcode, Übertragung und Bedeutung. Die Richtlinie hilft beim Prüfen von Änderungen; sie ist keine Garantie für das Verhalten einer beliebigen fremden API.

Die Änderung mit einem ausgearbeiteten Fall beschreiben

In unserem Beispiel enthält die alte Anfrage das Feld delivery_note als Text. Die neue Version erwartet den Text unter delivery_note.text. Beide Angaben sollen dieselbe Lieferanweisung „Tor B“ transportieren. Für die Umstellung genügt deshalb weder das Ersetzen einer URL noch ein erfolgreicher Verbindungsaufbau.

Prüfen Sie zusätzlich, wie Fehler und noch laufende Verarbeitung zurückgemeldet werden. Ein anderer Antwortaufbau kann den Aufrufer treffen, obwohl die Anfrage weiterhin akzeptiert wird.

Alt und neu unter denselben Bedingungen vergleichen

Bereiten Sie in einer geeigneten Testumgebung einen normalen Auftrag und einen Fall mit fehlender Lieferanweisung vor. Vergleichen Sie die gespeicherten Zieldaten und die sichtbare Rückmeldung. Klären Sie außerdem, ob die verwendeten Zugriffsrechte beide Versionen abdecken. Echte Aufträge sollten für diesen Vergleich nicht doppelt in zwei produktive Wege gesendet werden.

Umschalten mit offenen Vorgängen abstimmen

Legen Sie fest, ab welchem Punkt neue Anfragen den neuen Weg nutzen. Bereits gesendete, noch unbestätigte Anfragen brauchen eine Zuordnung, damit eine Wiederholung nicht als neuer Auftrag behandelt wird. Vereinbaren Sie einen Rückweg für neu eintreffende Anfragen und prüfen Sie gesondert, was mit bereits geschriebenen Daten geschieht. Das Zurücksetzen einer URL macht diese Änderungen nicht rückgängig.

Die alte Version kann aus diesem Datenfluss entfernt werden, wenn alle erfassten Aufrufer umgestellt und die offenen Vorgänge zugeordnet sind. Dokumentieren Sie den tatsächlich geprüften Stand statt allein das neue Versionsetikett.

Quellen

• Google AIP-180: Backwards compatibility