Wie schwer kann es also sein, eine API zu versionieren? Die Wahrheit ist, dass es nicht schwer ist, aber was schwer ist, ist die Aufrechterhaltung einer gewissen Vernunft, indem man sich nicht unnötig in eine verwirrende Anzahl von Versionen und Unterversionen verwickelt, die auf Dutzende von API-Endpunkten angewendet werden, mit unklaren Kompatibilitäten.
Business in a box.
Entdecken Sie unsere Lösungen.
Sprechen Sie mit unserem Vertriebsteam
Breaking Changes Schlecht! API Versioning Gut!
Wie jeder, der eine API erstellt oder regelmäßig nutzt, früher oder später erkennt, sind Breaking Changes sehr schlecht und können ein sehr ernsthafter Makel auf einer ansonsten nützlichen API sein. Ein Breaking Change ist eine Änderung im Verhalten einer API, die die Integration eines Benutzers stören kann und viel Frustration und Vertrauensverlust zwischen dem API-Anbieter und dem Benutzer zur Folge haben kann. Breaking Changes erfordern, dass Benutzer im Voraus benachrichtigt werden (mit begleitenden Entschuldigungen) anstatt einer Änderung, die einfach auftaucht, wie eine erfreuliche neue Funktion. Der Weg, um diese Frustration zu vermeiden, besteht darin, einer API-Version Versprechungen des API-Inhabers zu geben, dass es innerhalb einer einzelnen Version keine überraschenden Änderungen geben wird.
Wie schwer kann es also sein, einer API eine Version zu geben? Die Wahrheit ist: es ist nicht schwer, aber was schwer ist, ist etwas Vernunft zu bewahren, indem man nicht unnötig in eine verwirrende Anzahl von Versionen und Unterversionen verfällt, die über Dutzende von API-Endpunkten mit unklaren Kompatibilitäten angewendet werden.
Wir haben vor drei Jahren v1 der API eingeführt und nicht erkannt, dass sie bis heute stark gefragt sein würde. Wie haben wir es also geschafft, die beste E-Mail-Zustellungs-API über zwei Jahre lang bereitzustellen, aber dennoch die gleiche API-Version beizubehalten? Während es viele verschiedene Meinungen darüber gibt, wie REST-APIs versioniert werden sollten, hoffe ich, dass die Geschichte unseres bescheidenen, aber leistungsstarken v1 Ihnen auf Ihrem Weg zur API-Versionierungs-Erleuchtung leiten könnte.
REST Ist Best
API Governance
Mit einem ausgewählten Versionskonventionskonzept hatten wir mehr Fragen. Wann würden wir die Version erhöhen? Was ist eine grundlegende Änderung? Würden wir die gesamte API oder nur bestimmte Endpunkte neu versionieren? Bei SparkPost arbeiten mehrere Teams an verschiedenen Teilen unserer API. Innerhalb dieser Teams arbeiten die Menschen zu unterschiedlichen Zeiten an verschiedenen Endpunkten. Daher ist es sehr wichtig, dass unsere API im Gebrauch von Konventionen konsistent ist. Dies war größer als die Versionierung.
Wir etablierten eine Steuerungsgruppe, die Ingenieure aus jedem Team, ein Mitglied des Produktmanagementteams und unseren CTO umfasst. Diese Gruppe ist dafür verantwortlich, unsere API-Konventionen festzulegen, zu dokumentieren und durchzusetzen, und zwar teamübergreifend. Ein API-Governance-Slack-Kanal ist auch praktisch für lebhafte Diskussionen zu diesem Thema.
Die Steuerungsgruppe identifizierte eine Reihe von Möglichkeiten, wie Änderungen an der API eingeführt werden können, die für den Benutzer vorteilhaft sind und keine grundlegende Änderung darstellen. Dazu gehören:
Eine neue Ressource oder API-Endpunkt
Ein neuer optionaler Parameter
Eine Änderung an einem nicht öffentlichen API-Endpunkt
Ein neuer optionaler Schlüssel im JSON-POST-Body
Ein neuer Schlüssel, der im JSON-Antwort-Body zurückgegeben wird
Umgekehrt beinhaltete eine grundlegende Änderung alles, was die Integration eines Benutzers beeinträchtigen könnte, wie zum Beispiel:
Ein neuer erforderlicher Parameter
Ein neuer erforderlicher Schlüssel in POST-Bodies
Entfernung eines bestehenden Endpunkts
Entfernung einer bestehenden Endpunkt-Anforderungsmethode
Ein wesentlich unterschiedliches internes Verhalten eines API-Aufrufs – wie eine Änderung des Standardverhaltens.
The Big 1.0
Während wir diese Konventionen dokumentierten und diskutierten, kamen wir auch zu dem Schluss, dass es in unser aller (auch in unserem!) besten Interesse liegt, Änderungen an der API zu vermeiden, da die Verwaltung mehrerer Versionen einen erheblichen Aufwand mit sich bringt. Wir entschieden, dass es einige Dinge gibt, die wir mit unserer API korrigieren sollten, bevor wir uns auf „v1“ festlegen.
Das Versenden einer einfachen E-Mail erforderte viel zu viel Aufwand. Um „die einfachen Dinge einfach zu halten“, haben wir den POST-Body aktualisiert, um sicherzustellen, dass sowohl einfache als auch komplexe Anwendungsfälle unterstützt werden. Das neue Format war auch zukunftssicherer. Zweitens haben wir ein Problem mit dem Metrics-Endpunkt angesprochen. Dieser Endpunkt verwendete einen „group_by“-Parameter, der das Format des GET-Antwortkörpers so änderte, dass der erste Schlüssel der Wert des group_by-Parameters war. Das erschien uns nicht sehr REST-konform, also haben wir jedes group_by in einen separaten Endpunkt aufgeteilt. Schließlich haben wir jedes Endpunktes auditiert und kleine Änderungen hier und da vorgenommen, um sicherzustellen, dass sie den Standards entsprechen.
Accurate Dokumentation
Es ist wichtig, eine genaue und nutzbare API-Dokumentation zu haben, um Breaking Changes, ob absichtlich oder unabsichtlich, zu vermeiden. Wir haben uns entschieden, einen einfachen Ansatz zur API-Dokumentation zu verwenden, der eine Markdown-Sprache namens API Blueprint nutzt, um unsere Dokumentationen in Github zu verwalten. Unsere Community trägt dazu bei und verbessert diese Open-Source-Dokumentationen. Wir pflegen auch eine nicht öffentliche Sammlung von Dokumentationen in Github für interne APIs und Endpunkte.
Anfangs haben wir unsere Dokumentationen auf Apiary veröffentlicht, ein großartiges Tool zum Prototypen und Veröffentlichen von API-Dokumentationen. Allerdings funktioniert das Einbetten von Apiary auf unserer Website nicht auf mobilen Geräten, daher verwenden wir jetzt Jekyll, um statische Dokumentationen zu generieren. Unsere neuesten SparkPost API-Dokumentationen laden nun schnell und funktionieren gut auf mobilen Geräten, was wichtig für Entwickler ist, die nicht immer an ihrem Computer sitzen.
Trennung von Deployment und Release
Wir haben schon früh den wertvollen Trick gelernt, die Bereitstellung von einem Release zu trennen. Auf diese Weise ist es möglich, Änderungen häufig bereitzustellen, wenn sie durch kontinuierliche Lieferung und Bereitstellung bereit sind, aber wir kündigen sie nicht immer öffentlich an oder dokumentieren sie gleichzeitig. Es ist nicht ungewöhnlich für uns, einen neuen API-Endpunkt oder eine Verbesserung eines vorhandenen API-Endpunkts bereitzustellen und ihn innerhalb der Benutzeroberfläche oder mit internen Werkzeugen zu nutzen, bevor wir es öffentlich dokumentieren und unterstützen. So können wir einige Anpassungen für die Benutzerfreundlichkeit oder die Einhaltung von Standards vornehmen, ohne uns Sorgen über gefürchtete breaking changes machen zu müssen. Sobald wir mit der Änderung zufrieden sind, fügen wir sie unserer öffentlichen Dokumentation hinzu.
Mist!
Es ist nur fair zuzugeben, dass es Zeiten gab, in denen wir unseren Idealen der „keine Änderungen“ nicht gerecht wurden, und daraus kann man lernen. In einem Fall entschieden wir, dass es für die Nutzer besser wäre, wenn eine bestimmte Eigenschaft standardmäßig auf true anstatt auf false gesetzt wäre. Nachdem wir die Änderung bereitgestellt hatten, erhielten wir mehrere Beschwerden von Nutzern, da das Verhalten unerwartet geändert wurde. Wir machten die Änderung rückgängig und fügten eine Kontoebene-Einstellung hinzu – ein wesentlich benutzerfreundlicherer Ansatz, definitiv.
Gelegentlich sind wir versucht, aufgrund von Fehlerkorrekturen Änderungen einzuführen. Jedoch entschieden wir uns, diese Eigenheiten so zu belassen, um nicht die Integrationen der Kunden aus Gründen der Konsistenz zu gefährden.
Es gibt seltene Fälle, in denen wir die ernsthafte Entscheidung treffen, eine Änderung zu machen – wie das Veraltendeklarieren einer API-Ressource oder -Methode – im Interesse der größeren Benutzer-Community und nur, nachdem wir bestätigt haben, dass es kaum bis keine Auswirkungen auf die Benutzer hat. Zum Beispiel trafen wir die bewusste Entscheidung, das Antwortverhalten der Suppression API zu ändern, jedoch erst nach sorgfältiger Abwägung der Vorteile und Auswirkungen auf die Community und sorgfältiger Kommunikation der Änderung an unsere Nutzer. Wir würden jedoch niemals einen Change einführen, der auch nur entfernte Möglichkeiten hat, das Senden von Produkt-E-Mails eines Nutzers direkt zu beeinflussen.
