Eine API ist nicht allein deshalb kompatibel, weil sie denselben Pfad oder dieselbe Version beibehält. Ihre Konsumenten sind auch von der Datenstruktur, den Validierungsregeln, Standardwerten und dem Verhalten bei Fehlern abhängig. Wenn verschiedene Clients in unterschiedlichem Tempo aktualisiert werden, kann eine Änderung, die für das Serverteam geringfügig erscheint, eine mobile App, eine Drittanbieterintegration oder einen internen Prozess unterbrechen.
Eine Richtlinie zur Datenkompatibilität in PHP-APIs macht dieses Risiko zu einer Reihe ausdrücklicher Entscheidungen: Welche Änderungen sind zulässig, wie werden sie bereitgestellt und welche Tests müssen bestanden werden, bevor ein Vertrag außer Kraft gesetzt wird? Es gibt keine allgemeingültige Regel, die jede Änderung kompatibel macht; entscheidend ist, wie die einzelnen Konsumenten Daten lesen und senden.
Der Vertrag umfasst Daten, Validierung und Verhalten
Der Vertrag einer API umfasst mehr als das dokumentierte Schema. Dazu gehören Felder und ihre Typen, die Frage, ob sie ausgelassen werden können oder null sein dürfen, die Interpretation von Datumsangaben und Beträgen, die zulässigen Werte einer Anfrage, das Fehlerformat und die Garantien für die Antwort. Dazu gehören auch beobachtbare Regeln wie die Reihenfolge einer Sammlung, wenn Clients davon abhängen, oder die Stabilität einer Kennung.
In PHP bilden Transferobjekte, Validatoren und Serialisierer häufig Teile dieses Vertrags ab. Wer nur den Controller überprüft, kann inkompatible Änderungen übersehen, die sich in einer Validierungsregel, einer Antwortressource oder einer Zuordnung zwischen Modell und API verbergen. Dokumentieren Sie den Vertrag anhand dessen, was der Client tatsächlich beobachten kann, nicht anhand der internen Struktur von Klassen oder Tabellen.
Änderungen aus Sicht der Konsumenten klassifizieren
Die Klassifizierung ist ein Bewertungsinstrument, keine automatische Garantie. Eine additive Änderung erhält gewöhnlich die Funktionsfähigkeit von Clients, die unbekannte Felder ignorieren. Sie kann jedoch Konsumenten beeinträchtigen, die die Antwort in eine strikte Struktur umwandeln oder anhand eines geschlossenen Schemas validieren. Ebenso kann ein neues optionales Feld in einer Anfrage für ältere Clients unproblematisch sein, während ein verpflichtendes Feld es nicht ist.
- In der Regel additiv: ein optionales Feld zu einer Anfrage oder Antwort hinzufügen oder einen Wert zu einer Sammlung hinzufügen, sofern die Konsumenten solche Elemente tolerieren.
- Möglicherweise inkompatibel: ein Feld entfernen oder umbenennen, seinen Typ ändern, ein optionales Feld verpflichtend machen, das Format eines Fehlers ändern oder die Bedeutung eines bestehenden Werts verändern.
- Kontextabhängig: Reihenfolge, numerische Genauigkeit, Zeitzone, Statussemantik oder Paginierungskriterien ändern. Auch wenn sich das Schema nicht ändert, kann sich das Ergebnis für den Client verändern.
Identifizieren Sie vor der Freigabe einer Änderung die Konsumenten und prüfen Sie, wie sie die Daten verarbeiten. Ein unbekanntes Feld kann ignoriert werden, einen Validierungsfehler auslösen oder in eine Logik gelangen, die es nicht erwartet hat. Gehen Sie nicht davon aus, dass alle Sprachen, Bibliotheken oder Client-Versionen gleich reagieren.
Anfragen und Antworten vorsichtig weiterentwickeln
Bei Antworten ist das Hinzufügen eines Feldes sicherer, wenn berücksichtigt wird, dass strikte Clients zusätzliche Eigenschaften zurückweisen können. Ändern sich Bedeutung oder Typ eines Feldes, verwenden Sie es nicht stillschweigend weiter. Führen Sie ein neues Feld mit klarer Semantik ein, dokumentieren Sie seine Beziehung zum bisherigen Feld und behalten Sie beide während eines festgelegten Übergangszeitraums bei.
Bei Anfragen ist es entscheidend, zwischen fehlend, null und leer zu unterscheiden. In PHP kann eine Validierung, die das Fehlen eines Schlüssels genauso behandelt wie dessen Wert null, Daten löschen oder unerwartete Standardwerte anwenden. Definieren Sie die Bedeutung jedes Falls und testen Sie sowohl neue als auch ältere Clients. Erwägen Sie bei einem neuen Feld, sein Fehlen zunächst zu akzeptieren und ein kompatibles Verhalten festzulegen, statt es bereits bei der ersten Bereitstellung zu verlangen.
Die Versionierung von Pfaden ist nicht die einzige Möglichkeit. Ein Vertrag kann bei gleichbleibendem Pfad weiterentwickelt werden, wenn die Änderungen kompatibel sind. Andernfalls kann eine neue Version veröffentlicht werden, wenn die Änderungen inkompatibel sind und ein paralleler Betrieb sinnvoll ist. Dokumentieren Sie in beiden Fällen die Support-Richtlinie: Eine Versionsbezeichnung allein sagt nicht aus, wie lange ein Vertrag verfügbar bleibt.
Datenbank und API schrittweise bereitstellen
Eine sichere Bereitstellung trennt Änderungen am Speicher von der Aktivierung des neuen Verhaltens. Eine übliche Abfolge ist, das Schema zu erweitern, Code bereitzustellen, der sowohl mit der alten als auch mit der neuen Struktur arbeiten kann, bei Bedarf Daten zu migrieren und schließlich das neue Lesen oder Schreiben zu aktivieren. Alte Spalten oder Pfade werden erst später entfernt, wenn genügend Belege dafür vorliegen, dass sie nicht mehr benötigt werden.
Dieser Ansatz aus Erweiterung und Rückbau verhindert, dass eine Anwendungsversion eine noch nicht vorhandene Spalte voraussetzt oder dass eine neue Bereitstellung mit älteren Prozessen nicht mehr funktioniert. Berücksichtigen Sie bei Systemen mit mehreren Instanzen oder Hintergrund-Workern, dass während der Bereitstellung unterschiedliche Codeversionen gleichzeitig laufen können. Migrationen müssen mit diesem parallelen Betrieb kompatibel sein und für den Fall, dass eine Phase fehlschlägt, eine Wiederherstellungsstrategie vorsehen.
Eine schrittweise Aktivierung – etwa indem eine Funktion für einen kontrollierten Teil der Konsumenten freigeschaltet wird – kann die Auswirkungen begrenzen, ist aber weder eine öffentliche Bekanntgabe noch ein Ersatz für Kompatibilität. Verwenden Sie Aktivierungsmechanismen, wenn Sie damit das Verhalten beobachten und zurücknehmen können; legen Sie vorab fest, unter welchen Bedingungen die Ausweitung gestoppt wird.
Nutzung messen, ohne sensible Daten zu protokollieren
Um festzustellen, welche Konsumenten einen Vertrag noch verwenden, sollte die Telemetrie die relevante Version oder Funktion identifizieren, ohne Anforderungs- oder Antwortinhalte zu speichern, die personenbezogene Daten, Zugangsdaten oder Geschäftsdaten enthalten. Erfassen Sie nur minimale Signale wie Pfad, deklarierte Client-Version, Ergebnis und Zeitpunkt; beschränken Sie Zugriff und Aufbewahrungsdauer entsprechend den betrieblichen Erfordernissen und geltenden Verpflichtungen.
Das Signal muss für Entscheidungen nützlich sein. Unterscheiden Sie Anfragen echter Nutzer von Tests, Wiederholungsversuchen oder automatisiertem Datenverkehr; beobachten Sie außerdem Fehler, Latenz und Änderungen des Anfragevolumens. Gibt es keine zuverlässige Client-Kennung, leiten Sie die Identität nicht aus sensiblen Daten ab. Berücksichtigen Sie, dass Proxys, gemeinsam genutzte Schlüssel und Clients, die keine Version übermitteln, blinde Flecken verursachen können.
Einen Vertrag anhand überprüfbarer Kriterien außer Kraft setzen
Setzen Sie eine Version nicht allein deshalb außer Kraft, weil eine angekündigte Frist abgelaufen ist. Definieren Sie dem Risiko angemessene Signale und Schwellenwerte: dauerhaft ausbleibender identifizierbarer Datenverkehr, bestätigte Migration bekannter Integrationen, Stabilität der Nachfolgeversion und ein Supportverfahren für Ausnahmen. Besteht weiterhin unbekannter Datenverkehr, untersuchen Sie ihn, bevor Sie fehlende Identifizierbarkeit als fehlende Nutzung interpretieren.
Informieren Sie frühzeitig darüber, was sich ändert, wen es betrifft, welche Alternative besteht, welche Termine vorgesehen sind und wie die Migration getestet werden kann. Halten Sie die Informationen in einer für die konsumierenden Teams zugänglichen Dokumentation bereit und richten Sie einen Kanal ein, über den Inkompatibilitäten gemeldet werden können. Lässt sich eine Auswirkung nicht schnell zurücknehmen, ziehen Sie einen längeren Übergang oder den vorübergehenden parallelen Betrieb der Verträge in Betracht.
Checkliste vor der Veröffentlichung
- Wurden die betroffenen Felder, Typen, Null-Zulässigkeit, Standardwerte und Fehler dokumentiert?
- Wurde geprüft, wie tolerante und strikte Clients auf neue oder fehlende Felder reagieren?
- Decken Vertragstests bekannte Konsumenten und Grenzfälle der Validierung ab?
- Ermöglicht die Datenbankmigration den parallelen Betrieb mit älteren Anwendungsversionen?
- Sind genügend Metriken vorhanden, um Fehler und die Nutzung des Vertrags zu erkennen, ohne sensible Daten zu erfassen?
- Sind Verantwortliche, Kommunikation, Kriterien für ein Rollback und Bedingungen für die Entfernung des Alten festgelegt?
Eine hilfreiche Richtlinie verspricht nicht, dass keine Änderung jemals einen Client beeinträchtigen wird. Sie macht Annahmen ausdrücklich, begrenzt Überraschungen und ermöglicht evidenzbasierte Maßnahmen. Überprüfen Sie diese Entscheidungen bei jeder Vertragsänderung erneut, besonders wenn die API externe Konsumenten hat, deren Aktualisierungszyklus das Team nicht kontrolliert.
