Erreichen

Grow

Manage

Automate

Erreichen

Grow

Manage

Automate

RESTful API Versionsverwaltung Best Practices: Warum v1 die Nummer 1 ist

E-Mail

1 min read

RESTful API Versionsverwaltung Best Practices: Warum v1 die Nummer 1 ist

E-Mail

1 min read

RESTful API Versionsverwaltung Best Practices: Warum v1 die Nummer 1 ist

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.

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 ernstzunehmender Makel in einer ansonsten nützlichen API sein. Ein Breaking Change ist eine Änderung des Verhaltens einer API, die die Integration eines Benutzers beeinträchtigen kann und zu viel Frustration und Vertrauensverlust zwischen dem API-Anbieter und dem Benutzer führt. Breaking Changes erfordern, dass Benutzer im Voraus benachrichtigt werden (mit begleitenden Entschuldigungen), anstatt dass einfach eine Änderung erscheint, wie zum Beispiel eine erfreuliche neue Funktion. Der Weg, um diese Frustration zu vermeiden, besteht darin, eine API zu versionieren, mit der Zusicherung des API-Besitzers, dass innerhalb einer einzigen Version keine überraschenden Änderungen eingeführt werden.

Wie schwer kann es also sein, eine API zu versionieren? Die Wahrheit ist, dass es nicht schwer ist, aber was schwierig ist, ist, einen klaren Kopf zu bewahren, indem man sich nicht unnötig in eine verwirrende Anzahl von Versionen und Unterversionen verstrickt, die über Dutzende von API-Endpunkten mit unklaren Kompatibilitäten angewendet werden.

Wir haben vor drei Jahren v1 der API eingeführt und nicht damit gerechnet, dass es bis heute so erfolgreich sein würde. Wie haben wir es also geschafft, über zwei Jahre lang die beste E-Mail-Delivery-API bereitzustellen und die gleiche API-Version beizubehalten? Während es viele verschiedene Meinungen darüber gibt, wie man REST-APIs versioniert, hoffe ich, dass die Geschichte unseres bescheidenen, aber leistungsstarken v1 Ihnen auf Ihrem Weg zur API-Versionierungserleuchtung helfen kann.

REST Ist Best

Die SparkPost API stammt aus der Zeit, als wir noch Message Systems waren, bevor unsere Abenteuer in der Cloud begannen. Damals waren wir mit den letzten Vorbereitungen für den Beta-Start von Momentum 4 beschäftigt. Dies war ein großes Upgrade auf die Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 enthielt ein völlig neues UI, Echtzeitanalysen und am wichtigsten eine neue Web-API für die Nachrichteneinfügung und -erzeugung, die Verwaltung von Vorlagen und das Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar das UI mit API-Endpunkten interagieren würde.

Einer der frühesten und besten Entscheidungen, die wir getroffen haben, war, einen RESTful-Stil zu übernehmen. Seit den späten 2000er Jahren sind repräsentationale Status-Übergaben (REST) basierte Web-APIs der De-facto-Standard der Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern leicht, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java –, unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen oder sich darum kümmern zu müssen.

Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Doch innerhalb weniger Monate befand sich die Beta in den Händen einiger Kunden, und wir begannen mit dem Ausbau unseres Cloud-Dienstes. Zeit, zu versionieren. Wir bewerteten zwei Versionierungskonventionen. Die erste bestand darin, die Versionierung direkt in die URI einzufügen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist eindeutiger und weniger kompliziert, was für Entwickler einfacher ist. Da wir Entwickler lieben, war dies die logische Wahl.

Die SparkPost API stammt aus der Zeit, als wir noch Message Systems waren, bevor unsere Abenteuer in der Cloud begannen. Damals waren wir mit den letzten Vorbereitungen für den Beta-Start von Momentum 4 beschäftigt. Dies war ein großes Upgrade auf die Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 enthielt ein völlig neues UI, Echtzeitanalysen und am wichtigsten eine neue Web-API für die Nachrichteneinfügung und -erzeugung, die Verwaltung von Vorlagen und das Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar das UI mit API-Endpunkten interagieren würde.

Einer der frühesten und besten Entscheidungen, die wir getroffen haben, war, einen RESTful-Stil zu übernehmen. Seit den späten 2000er Jahren sind repräsentationale Status-Übergaben (REST) basierte Web-APIs der De-facto-Standard der Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern leicht, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java –, unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen oder sich darum kümmern zu müssen.

Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Doch innerhalb weniger Monate befand sich die Beta in den Händen einiger Kunden, und wir begannen mit dem Ausbau unseres Cloud-Dienstes. Zeit, zu versionieren. Wir bewerteten zwei Versionierungskonventionen. Die erste bestand darin, die Versionierung direkt in die URI einzufügen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist eindeutiger und weniger kompliziert, was für Entwickler einfacher ist. Da wir Entwickler lieben, war dies die logische Wahl.

Die SparkPost API stammt aus der Zeit, als wir noch Message Systems waren, bevor unsere Abenteuer in der Cloud begannen. Damals waren wir mit den letzten Vorbereitungen für den Beta-Start von Momentum 4 beschäftigt. Dies war ein großes Upgrade auf die Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 enthielt ein völlig neues UI, Echtzeitanalysen und am wichtigsten eine neue Web-API für die Nachrichteneinfügung und -erzeugung, die Verwaltung von Vorlagen und das Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar das UI mit API-Endpunkten interagieren würde.

Einer der frühesten und besten Entscheidungen, die wir getroffen haben, war, einen RESTful-Stil zu übernehmen. Seit den späten 2000er Jahren sind repräsentationale Status-Übergaben (REST) basierte Web-APIs der De-facto-Standard der Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern leicht, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java –, unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen oder sich darum kümmern zu müssen.

Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Doch innerhalb weniger Monate befand sich die Beta in den Händen einiger Kunden, und wir begannen mit dem Ausbau unseres Cloud-Dienstes. Zeit, zu versionieren. Wir bewerteten zwei Versionierungskonventionen. Die erste bestand darin, die Versionierung direkt in die URI einzufügen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist eindeutiger und weniger kompliziert, was für Entwickler einfacher ist. Da wir Entwickler lieben, war dies die logische Wahl.

API Governance

Mit einer ausgewählten Versionierungskonvention hatten wir weitere Fragen. Wann würden wir die Version erhöhen? Was ist eine breaking change?  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 Personen zu unterschiedlichen Zeiten an unterschiedlichen Endpunkten. Daher ist es sehr wichtig, dass unsere API konsistent in der Verwendung von Konventionen ist. Das war größer als die Versionierung.

Wir haben eine Governance-Gruppe gebildet, die Ingenieure aus jedem Team, ein Mitglied des Produktmanagement-Teams und unseren CTO umfasst. Diese Gruppe ist dafür verantwortlich, unsere API-Konventionen teamübergreifend festzulegen, zu dokumentieren und durchzusetzen. Ein API-Governance-Slack-Kanal ist ebenfalls nützlich für lebhafte Diskussionen zu diesem Thema.

Die Governance-Gruppe identifizierte eine Reihe von Möglichkeiten, wie Änderungen in die API eingeführt werden können, die für den Benutzer vorteilhaft sind und keine breaking change darstellen. Diese schließen ein:

  • Ein neuer 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 im JSON-Antwort-Body


Umgekehrt beinhaltete eine breaking change alles, was die Integration eines Benutzers unterbrechen könnte, wie zum Beispiel:

  • Ein neuer erforderlicher Parameter

  • Ein neuer erforderlicher Schlüssel in POST-Bodys

  • Entfernung eines vorhandenen Endpunkts

  • Entfernung einer bestehenden Endpunktanforderungsmethode

  • Ein wesentlich unterschiedliches internes Verhalten eines API-Aufrufs – wie z. B. eine Änderung des Standardverhaltens.

The Big 1.0

Als wir diese Konventionen dokumentierten und diskutierten, kamen wir auch zu dem Schluss, dass es in jedermanns (einschließlich unserer!) bestem Interesse war, Änderungen an der API zu vermeiden, da die Verwaltung mehrerer Versionen einen erheblichen Overhead mit sich bringt. Wir beschlossen, dass es einige Dinge gab, die wir mit unserer API beheben sollten, bevor wir uns zu „v1“ verpflichten.

Das Senden einer einfachen E-Mail erforderte viel zu viel Aufwand. Um „die einfachen Dinge einfach zu halten“ aktualisierten wir den POST-Body, um sicherzustellen, dass sowohl einfache als auch komplexe Anwendungsfälle berücksichtigt werden. Das neue Format war auch zukunftssicherer. Zweitens haben wir ein Problem mit dem Metrics-Endpunkt angegangen. 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 schien nicht sehr RESTful, daher haben wir jede Gruppierung in einen separaten Endpunkt aufgeteilt. Schließlich haben wir jeden Endpunkt überprüft und hier und da kleinere Änderungen vorgenommen, um sicherzustellen, dass sie den Standards entsprachen.

Accurate Dokumentation

Es ist wichtig, genaue und brauchbare API-Dokumentationen zu haben, um Änderungen zu vermeiden, die absichtlich oder unabsichtlich entstehen. Wir haben uns entschieden, einen einfachen Ansatz für die API-Dokumentation zu verwenden, der eine Markdown-Sprache namens API Blueprint nutzt und unsere Dokumentationen in Github zu verwalten. Unsere Community trägt zu diesen Open-Source-Dokumenten bei und verbessert sie.  Wir pflegen auch eine nicht öffentliche Sammlung von Dokumentationen in Github für interne APIs und Endpunkte.

Ursprünglich haben wir unsere Dokumentationen auf Apiary veröffentlicht, ein großartiges Werkzeug für die Planung und Veröffentlichung von API-Dokumentationen. Allerdings funktioniert das Einbetten von Apiary in unsere Website nicht auf mobilen Geräten, daher verwenden wir jetzt Jekyll, um statische Dokumentationen zu erstellen.  Unsere neuesten SparkPost API Dokumentationen laden jetzt 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 „keine Änderungen, die zu Problemen führen“ nicht gerecht geworden sind, und daraus sollte man lernen. Bei einer Gelegenheit entschieden wir, dass es für die Benutzer besser wäre, wenn eine bestimmte Eigenschaft standardmäßig auf „true“ anstatt auf „false“ eingestellt wäre. Nachdem wir die Änderung implementiert hatten, erhielten wir mehrere Beschwerden von Benutzern, da sich das Verhalten unerwartet geändert hatte.  Wir machten die Änderung rückgängig und fügten eine Kontoeinstellung hinzu – ein viel benutzerfreundlicherer Ansatz, ganz sicher.

Gelegentlich sind wir versucht, aufgrund von Fehlerbehebungen Änderungen, die zu Problemen führen könnten, einzuführen. Allerdings entschieden wir, diese Eigenheiten in Ruhe zu lassen, anstatt das Risiko einzugehen, die Integrationen der Kunden um der Konsistenz willen zu stören.

Es gibt seltene Fälle, in denen wir die ernsthafte Entscheidung trafen, eine Änderung, die zu Problemen führen könnte, vorzunehmen – wie das Veralten einer API-Ressource oder Methode – im Interesse der Benutzer-Community insgesamt und nur nach Bestätigung, dass es nur geringe oder keine Auswirkungen auf die Benutzer gibt. Beispielsweise trafen wir bewusst die 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 Benutzer. Wir würden jedoch niemals eine Änderung einführen, die auch nur eine entfernte Möglichkeit hat, das Senden einer Produktions-E-Mail eines Benutzers direkt zu beeinträchtigen.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

Lassen Sie uns Sie mit einem Bird-Experten verbinden.
Erleben Sie die volle Macht des Bird in 30 Minuten.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.

R

Erreichen

G

Grow

M

Manage

A

Automate

Unternehmen

Newsletter

Bleiben Sie mit Bird auf dem Laufenden durch wöchentliche Updates in Ihrem Posteingang.

Durch die Übermittlung stimmen Sie zu, dass Bird Sie bezüglich unserer Produkte und Dienstleistungen kontaktieren darf.

Sie können sich jederzeit abmelden. Weitere Informationen zur Datenverarbeitung finden Sie in Birds Datenschutzerklärung.