Was macht API-Verträge?
Ein Vertrag ist ein Versprechen an Code, den Sie nicht kontrollieren und nicht reparieren können. Das unterscheidet API-Änderungen von internem Refactoring: Die Kosten eines Fehlers trägt jemand anderes, zu einem Zeitpunkt, den Sie nicht wählen.
Design
Benennen Sie Ressourcen als Nomen und lassen Sie die Methode das Verb tragen. Modellieren Sie das Ding, nicht den Bildschirm, der es aktuell anzeigt – eine Payload, die um die heutige UI geformt ist, wird beim nächsten Redesign falsch.
Seien Sie bewusst, was Sie offenlegen. Jedes Feld, das Sie zurückgeben, ist ein Feld, das Sie weiterhin zurückgeben müssen. Interne Identifikatoren, Zeilenversionen und Implementierungsdetails lassen Ihr Schema in den Code des Aufrufers durchsickern und frieren es dort ein.
Machen Sie Operationen idempotent, wenn der Aufrufer wiederholen könnte – also jede Operation, die über ein Netzwerk erreichbar ist. Geben Sie dem Aufrufer einen Idempotenzschlüssel für alles, was erstellt oder belastet, damit eine Wiederholung nach einem Timeout nichts verdoppeln kann.
Geben Sie ein konsistentes Fehlermodell zurück: einen stabilen maschinenlesbaren Code, eine menschenlesbare Nachricht und das Feld, auf das sich eine Validierungsfehler bezieht. Aufrufer verzweigen anhand des Codes, also ist er Teil des Vertrags – das Ändern eines Codes ist ein Breaking Change, auch wenn die Form unverändert bleibt.
Paginieren Sie jede Liste ab der ersten Version. Ein Endpunkt, der alles zurückgibt, funktioniert, bis die Tabelle wächst, und scheitert dann für den Kunden mit den meisten Daten. Bevorzugen Sie einen Cursor gegenüber einem Offset, wenn Zeilen gleichzeitig eingefügt werden.
Was einen Aufrufer bricht
Breaking, unabhängig davon, was die Schema-Sprache erlaubt:
- Entfernen oder Umbenennen eines Feldes, eines Endpunkts, einer Methode oder eines Enum-Werts.
- Ein optionales Request-Feld erforderlich machen oder die akzeptierten Werte eines Feldes einschränken.
- Ändern eines Typs, einschließlich Integer zu String und eines einzelnen Werts zu einer Liste.
- Die Bedeutung eines vorhandenen Feldes ändern, während Name und Typ erhalten bleiben – die schlimmste Art, da nichts laut scheitert und die Daten leise falsch sind.
- Hinzufügen eines neuen erforderlichen Feldes zu einem Request.
- Ändern eines Fehlercodes oder eines HTTP-Status für eine bestehende Bedingung.
- Verschärfen eines Standardwerts oder ändern, was passiert, wenn ein Feld weggelassen wird.
Sicher: Hinzufügen eines optionalen Request-Feldes, Hinzufügen eines Response-Feldes, Hinzufügen eines neuen Endpunkts oder einer neuen Methode, Hinzufügen eines Enum-Werts nur wenn jeder Verbraucher bereits unbekannte Werte toleriert – überprüfen Sie das, statt es anzunehmen.
In Protobuf: Verwenden oder nummerieren Sie ein Feld-Tag niemals wieder, und reservieren Sie das Tag und den Namen, wenn Sie ein Feld entfernen. Ein wiederverwendetes Tag dekodiert alte Daten in das neue Feld und beschädigt sie leise.
Einen Vertrag sicher ändern
Fügen Sie hinzu, bevor Sie entfernen, und lassen Sie beide mindestens eine Version lang funktionieren:
- Fügen Sie das neue Feld oder die neue Methode neben dem alten hinzu.
- Schreiben Sie beide, lesen Sie das neue mit einem Fallback auf das alte.
- Migrieren Sie die Verbraucher und bestätigen Sie, dass jeder umgestellt hat.
- Entfernen Sie den alten Pfad in einer späteren Version.
Versionieren Sie, wenn sich die Ressource tatsächlich in ihrer Bedeutung ändert, nicht bei jeder Ergänzung. Eine Version pro Änderung vervielfacht die Oberfläche, die Sie am Leben erhalten müssen.
Auslieferungsreihenfolge
Generierter Code und Server werden separat ausgerollt, und die Lücke ist der Ort, an dem Ausfälle leben. Rollen Sie zuerst die Seite aus, die beide Formen toleriert: Verbraucher, die das neue Feld akzeptieren, bevor Produzenten es senden; Produzenten, die den neuen Request akzeptieren, bevor Aufrufer ihn senden.
Wenn ein Schema über ein Gateway, einen Proxy oder generierte Clients geteilt wird, muss jede Komponente im Pfad neu generiert und bereitgestellt werden. Ein Feld, das zum Dienst hinzugefügt, aber nicht zur davorliegenden Schicht hinzugefügt wurde, verschwindet, bevor es den Aufrufer erreicht, und die eigenen Tests des Dienstes werden es nicht bemerken.
Überprüfen
Überprüfen Sie die tatsächlichen Verbraucher, bevor Sie eine Form ändern – durchsuchen Sie die Aufrufer, statt der Dokumentation des Vertrags zu vertrauen.
Testen Sie den Vertrag selbst: Ein Test, der die serialisierte Form überprüft, fängt eine versehentliche Umbenennung, die ein Unit-Test des Handlers völlig übersehen würde.