RESTful API Versionsverwaltung Best Practices: Warum v1 die Nummer 1 ist
Chris McFadden
24.05.2017
1 min read
Wichtige Erkenntnisse
API-Versionierung verhindert disruptive Änderungen und bewahrt das Vertrauen zwischen API-Anbietern und Entwicklern.
Klare Versionskonventionen helfen, ein chaotisches Durcheinander von Versionen über Endpunkte hinweg zu vermeiden.
RESTful APIs zusammen mit einfachen, expliziten Versions-URIs halten Integrationen für Entwickler intuitiv.
Governance-Gruppen sorgen für Konsistenz über Teams hinweg und verhindern zufällige disruptive Änderungen.
Nicht alle Änderungen erfordern eine neue Version – nur diejenigen, die bestehende Integrationen unterbrechen.
Gute Dokumentation ist essentiell, um Verwirrung zu vermeiden und versehentliche disruptive Änderungen zu verhindern.
Die Trennung von Bereitstellung und Veröffentlichung ermöglicht es Teams, Endpunkte sicher zu testen und zu verfeinern, bevor sie angekündigt werden.
Wenn disruptive Änderungen unvermeidlich sind, müssen sie sorgfältig bewertet und kommuniziert werden.
Q&A Highlights
Warum ist API-Versionierung wichtig?
Es verhindert unerwartete Breaking-Changes für Entwickler, die sich in Ihre API integrieren, schützt das Vertrauen und sorgt für langfristige Stabilität von Anwendungen, die auf konsistentes Verhalten angewiesen sind.
Was sind Breaking Changes in einer API?
Jede Änderung, die das Verhalten bestehender Integrationen verändert — wie das Entfernen von Endpunkten, das Ändern von Standardwerten, das Hinzufügen erforderlicher Felder oder das Ändern von Antwortformaten.
Warum hat SparkPost sich entschieden, REST als Grundlage für ihre API zu nutzen?
Die Verwendung von HTTP und JSON durch REST erleichtert es Entwicklern aus verschiedenen Sprachen (PHP, Ruby, Java usw.), ohne spezielles Wissen über die darunterliegenden Systeme zu integrieren.
Wie hat SparkPost seine Versionierungsmethode festgelegt?
Sie bewerteten die Accept-Header-Versionierung im Vergleich zur URI-Versionierung und entschieden sich für die URI-Versionierung, da sie explizit, einfach und entwicklerfreundlicher ist.
Welche Rolle spielt eine API Governance-Gruppe?
Es legt Standards fest, sorgt für Konsistenz und verhindert, dass Teams Änderungen einführen, die im Widerspruch zu Konventionen stehen oder die Kompatibilität beeinträchtigen.
Welche Arten von Änderungen gelten nicht als breaking?
Hinzufügen neuer optionaler Parameter, Einführen neuer Endpunkte, Hinzufügen neuer Schlüssel in JSON-Nutzlasten oder Ändern nicht-öffentlicher Endpunkte — alles, was das bestehende Verhalten nicht stört.
Welche Änderungen gelten als breaking?
Hinzufügen erforderlicher Parameter, Entfernen von Endpunkten, Ändern der Standardverhalten, Ändern der Antwortstruktur oder Einführen erforderlicher JSON-Felder.
Warum ist genaue Dokumentation essenziell?
Es verhindert unbeabsichtigte Breaking Changes, hilft Entwicklern, das Verhalten zu verstehen, und stellt sicher, dass Teams die API zuverlässig aktualisieren. SparkPost verwendete Markdown (API Blueprint) und GitHub, um Klarheit und Offenheit zu bewahren.
Was ist der Vorteil, die Bereitstellung von der Freigabe zu trennen?
Teams können kontinuierlich neue Endpunkte oder Verbesserungen intern bereitstellen, diese in realen Workflows testen, Verhaltensweisen verfeinern und erst dann öffentlich freigeben, wenn sie stabil sind — um eine vorzeitige und potenziell störende Veröffentlichung zu vermeiden.
Was passiert, wenn eine Breaking Change nötig wird?
Es muss selten sein, durch klare Vorteile gerechtfertigt, sorgfältig auf Benutzerwirkung evaluiert und umfassend kommuniziert werden. Beispiel: Anpassung der Suppression API nur nach Bestätigung minimaler Auswirkungen und Bereitstellung einer Benachrichtigung.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es nicht schwierig ist, aber was schwierig ist, ist, einen gewissen Verstand zu behalten, 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.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es nicht schwierig ist, aber was schwierig ist, ist, einen gewissen Verstand zu behalten, 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.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es nicht schwierig ist, aber was schwierig ist, ist, einen gewissen Verstand zu behalten, 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.
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.
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.
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.
Breaking Changes Schlecht! API Versioning Gut!
Wie jeder, der eine API aufgebaut hat oder regelmäßig nutzt, früher oder später erkennt, sind Breaking Changes sehr schlecht und können ein sehr ernsthaftes Manko an einer ansonsten nützlichen API sein. Ein Breaking Change ist eine Änderung am Verhalten einer API, die die Integration eines Benutzers brechen und zu viel Frustration und Vertrauensverlust zwischen dem API-Anbieter und dem Benutzer führen kann. Breaking Changes erfordern, dass Benutzer im Voraus benachrichtigt werden (mit begleitendem Mea Culpa), anstatt dass eine Änderung einfach auftaucht, wie zum Beispiel ein freudiges neues Feature. Der Weg, um diese Frustration zu vermeiden, ist, eine API mit der Zusicherung des API-Eigentümers zu versionieren, dass innerhalb einer einzigen Version keine überraschenden Änderungen eingeführt werden.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es das nicht ist, aber was schwierig ist, ist, etwas Verstand zu bewahren, indem man nicht unnötig in eine schwindelerregende Anzahl von Versionen und Subversionen verfällt, die über Dutzende von API-Endpunkten mit unklaren Kompatibilitäten angewendet werden.
Wir haben v1 der API vor drei Jahren eingeführt und haben nicht erkannt, dass sie bis heute stark genutzt wird. Also, wie haben wir es geschafft, die beste E-Mail-Zustellungs-API seit über zwei Jahren bereitzustellen, aber dennoch dieselbe API-Version beizubehalten? Diese Stabilität ist entscheidend für Entwickler, die Anwendungen mit E-Mail-APIs in Cloud-Infrastruktur erstellen, wo Zuverlässigkeit und Konsistenz von größter Bedeutung sind. Während es viele verschiedene Meinungen darüber gibt, wie man REST-APIs versioniert, hoffe ich, dass die Geschichte unseres bescheidenen, aber leistungsstarken v1 Sie auf Ihrem Weg zur API-Versionierungserleuchtung leiten kann.
Wie jeder, der eine API aufgebaut hat oder regelmäßig nutzt, früher oder später erkennt, sind Breaking Changes sehr schlecht und können ein sehr ernsthaftes Manko an einer ansonsten nützlichen API sein. Ein Breaking Change ist eine Änderung am Verhalten einer API, die die Integration eines Benutzers brechen und zu viel Frustration und Vertrauensverlust zwischen dem API-Anbieter und dem Benutzer führen kann. Breaking Changes erfordern, dass Benutzer im Voraus benachrichtigt werden (mit begleitendem Mea Culpa), anstatt dass eine Änderung einfach auftaucht, wie zum Beispiel ein freudiges neues Feature. Der Weg, um diese Frustration zu vermeiden, ist, eine API mit der Zusicherung des API-Eigentümers zu versionieren, dass innerhalb einer einzigen Version keine überraschenden Änderungen eingeführt werden.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es das nicht ist, aber was schwierig ist, ist, etwas Verstand zu bewahren, indem man nicht unnötig in eine schwindelerregende Anzahl von Versionen und Subversionen verfällt, die über Dutzende von API-Endpunkten mit unklaren Kompatibilitäten angewendet werden.
Wir haben v1 der API vor drei Jahren eingeführt und haben nicht erkannt, dass sie bis heute stark genutzt wird. Also, wie haben wir es geschafft, die beste E-Mail-Zustellungs-API seit über zwei Jahren bereitzustellen, aber dennoch dieselbe API-Version beizubehalten? Diese Stabilität ist entscheidend für Entwickler, die Anwendungen mit E-Mail-APIs in Cloud-Infrastruktur erstellen, wo Zuverlässigkeit und Konsistenz von größter Bedeutung sind. Während es viele verschiedene Meinungen darüber gibt, wie man REST-APIs versioniert, hoffe ich, dass die Geschichte unseres bescheidenen, aber leistungsstarken v1 Sie auf Ihrem Weg zur API-Versionierungserleuchtung leiten kann.
Wie jeder, der eine API aufgebaut hat oder regelmäßig nutzt, früher oder später erkennt, sind Breaking Changes sehr schlecht und können ein sehr ernsthaftes Manko an einer ansonsten nützlichen API sein. Ein Breaking Change ist eine Änderung am Verhalten einer API, die die Integration eines Benutzers brechen und zu viel Frustration und Vertrauensverlust zwischen dem API-Anbieter und dem Benutzer führen kann. Breaking Changes erfordern, dass Benutzer im Voraus benachrichtigt werden (mit begleitendem Mea Culpa), anstatt dass eine Änderung einfach auftaucht, wie zum Beispiel ein freudiges neues Feature. Der Weg, um diese Frustration zu vermeiden, ist, eine API mit der Zusicherung des API-Eigentümers zu versionieren, dass innerhalb einer einzigen Version keine überraschenden Änderungen eingeführt werden.
Also, wie schwer kann es sein, eine API zu versionieren? Die Wahrheit ist, dass es das nicht ist, aber was schwierig ist, ist, etwas Verstand zu bewahren, indem man nicht unnötig in eine schwindelerregende Anzahl von Versionen und Subversionen verfällt, die über Dutzende von API-Endpunkten mit unklaren Kompatibilitäten angewendet werden.
Wir haben v1 der API vor drei Jahren eingeführt und haben nicht erkannt, dass sie bis heute stark genutzt wird. Also, wie haben wir es geschafft, die beste E-Mail-Zustellungs-API seit über zwei Jahren bereitzustellen, aber dennoch dieselbe API-Version beizubehalten? Diese Stabilität ist entscheidend für Entwickler, die Anwendungen mit E-Mail-APIs in Cloud-Infrastruktur erstellen, wo Zuverlässigkeit und Konsistenz von größter Bedeutung sind. Während es viele verschiedene Meinungen darüber gibt, wie man REST-APIs versioniert, hoffe ich, dass die Geschichte unseres bescheidenen, aber leistungsstarken v1 Sie auf Ihrem Weg zur API-Versionierungserleuchtung leiten kann.
REST Ist Best
Die SparkPost API stammt aus der Zeit, als wir Message Systems waren, vor unseren Abenteuern in der Cloud. Damals waren wir damit beschäftigt, die letzten Vorbereitungen für den Beta-Start von Momentum 4 zu treffen. Dies war ein großes Upgrade auf Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 beinhaltete eine völlig neue Benutzeroberfläche, Echtzeitanalysen und vor allem eine neue Web-API für Nachrichteninjektion und -generierung, Verwaltung von Vorlagen und Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar die Benutzeroberfläche mit API-Endpunkten interagieren würde.
Eine der frühesten und besten Entscheidungen, die wir getroffen haben, war die Übernahme eines RESTful-Stils. Seit den späten 2000er Jahren sind representational state transfer (REST)-basierte Web-APIs der De-facto-Standard für Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern einfach, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java – sich in unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen zu müssen oder sich darum zu kümmern. Der Aufbau von Cloud-nativen APIs in großem Maßstab kann jedoch unerwartete Infrastrukturherausforderungen mit sich bringen, wie die DNS-Skalierungsgrenzen, auf die wir in AWS stießen, als wir API-Verkehr mit hohem Volumen bewältigten.
Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war jedoch nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Innerhalb weniger Monate befand sich die Beta jedoch in den Händen einiger Kunden, und wir begannen, unseren Cloud-Service auszubauen. Es war Zeit zu versionieren. Wir haben zwei Versionierungskonventionen evaluiert.
Versionierungsansatz | Wie es funktioniert | Kompromiss |
|---|---|---|
URI-Versionierung | Version im Endpunktpfad enthalten | Explizit und leicht verständlich |
Accept Header-Versionierung | Version über HTTP-Header übergeben | Weniger sichtbar, komplexer für Entwickler |
Die erste Möglichkeit bestand darin, die Versionierung direkt in die URI zu setzen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist expliziter und weniger kompliziert, was es Entwicklern erleichtert. Da wir Entwickler lieben, war dies die logische Wahl.
Die SparkPost API stammt aus der Zeit, als wir Message Systems waren, vor unseren Abenteuern in der Cloud. Damals waren wir damit beschäftigt, die letzten Vorbereitungen für den Beta-Start von Momentum 4 zu treffen. Dies war ein großes Upgrade auf Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 beinhaltete eine völlig neue Benutzeroberfläche, Echtzeitanalysen und vor allem eine neue Web-API für Nachrichteninjektion und -generierung, Verwaltung von Vorlagen und Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar die Benutzeroberfläche mit API-Endpunkten interagieren würde.
Eine der frühesten und besten Entscheidungen, die wir getroffen haben, war die Übernahme eines RESTful-Stils. Seit den späten 2000er Jahren sind representational state transfer (REST)-basierte Web-APIs der De-facto-Standard für Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern einfach, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java – sich in unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen zu müssen oder sich darum zu kümmern. Der Aufbau von Cloud-nativen APIs in großem Maßstab kann jedoch unerwartete Infrastrukturherausforderungen mit sich bringen, wie die DNS-Skalierungsgrenzen, auf die wir in AWS stießen, als wir API-Verkehr mit hohem Volumen bewältigten.
Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war jedoch nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Innerhalb weniger Monate befand sich die Beta jedoch in den Händen einiger Kunden, und wir begannen, unseren Cloud-Service auszubauen. Es war Zeit zu versionieren. Wir haben zwei Versionierungskonventionen evaluiert.
Versionierungsansatz | Wie es funktioniert | Kompromiss |
|---|---|---|
URI-Versionierung | Version im Endpunktpfad enthalten | Explizit und leicht verständlich |
Accept Header-Versionierung | Version über HTTP-Header übergeben | Weniger sichtbar, komplexer für Entwickler |
Die erste Möglichkeit bestand darin, die Versionierung direkt in die URI zu setzen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist expliziter und weniger kompliziert, was es Entwicklern erleichtert. Da wir Entwickler lieben, war dies die logische Wahl.
Die SparkPost API stammt aus der Zeit, als wir Message Systems waren, vor unseren Abenteuern in der Cloud. Damals waren wir damit beschäftigt, die letzten Vorbereitungen für den Beta-Start von Momentum 4 zu treffen. Dies war ein großes Upgrade auf Version 3.x, unser marktführendes On-Premise-MTA. Momentum 4 beinhaltete eine völlig neue Benutzeroberfläche, Echtzeitanalysen und vor allem eine neue Web-API für Nachrichteninjektion und -generierung, Verwaltung von Vorlagen und Abrufen von E-Mail-Metriken. Unsere Vision war eine API-First-Architektur – bei der sogar die Benutzeroberfläche mit API-Endpunkten interagieren würde.
Eine der frühesten und besten Entscheidungen, die wir getroffen haben, war die Übernahme eines RESTful-Stils. Seit den späten 2000er Jahren sind representational state transfer (REST)-basierte Web-APIs der De-facto-Standard für Cloud-APIs. Die Verwendung von HTTP und JSON macht es Entwicklern einfach, unabhängig davon, welche Programmiersprache sie verwenden – PHP, Ruby und Java – sich in unsere API zu integrieren, ohne unsere zugrunde liegende Technologie kennen zu müssen oder sich darum zu kümmern. Der Aufbau von Cloud-nativen APIs in großem Maßstab kann jedoch unerwartete Infrastrukturherausforderungen mit sich bringen, wie die DNS-Skalierungsgrenzen, auf die wir in AWS stießen, als wir API-Verkehr mit hohem Volumen bewältigten.
Die Entscheidung für die RESTful-Architektur war einfach. Die Wahl einer Versionierungskonvention war jedoch nicht so einfach. Zunächst haben wir die Frage der Versionierung umgangen, indem wir die Beta überhaupt nicht versioniert haben. Innerhalb weniger Monate befand sich die Beta jedoch in den Händen einiger Kunden, und wir begannen, unseren Cloud-Service auszubauen. Es war Zeit zu versionieren. Wir haben zwei Versionierungskonventionen evaluiert.
Versionierungsansatz | Wie es funktioniert | Kompromiss |
|---|---|---|
URI-Versionierung | Version im Endpunktpfad enthalten | Explizit und leicht verständlich |
Accept Header-Versionierung | Version über HTTP-Header übergeben | Weniger sichtbar, komplexer für Entwickler |
Die erste Möglichkeit bestand darin, die Versionierung direkt in die URI zu setzen, und die zweite darin, einen Accept-Header zu verwenden. Die erste Option ist expliziter und weniger kompliziert, was es Entwicklern erleichtert. 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 Menschen zu unterschiedlichen Zeiten an verschiedenen Endpunkten. Daher ist es sehr wichtig, dass unsere API in der Verwendung von Konventionen konsistent ist. Dies war größer als die Versionierung.
Wir haben eine Governance-Gruppe eingerichtet, die Ingenieure jeder Gruppe, ein Mitglied des Produktmanagement-Teams und unseren CTO umfasst. Diese Gruppe ist dafür verantwortlich, unsere API-Konventionen für alle Teams zu etablieren, zu dokumentieren und durchzusetzen. Auch ein API-Governance Slack-Kanal ist nützlich für lebhafte Diskussionen zu diesem Thema.
Die Governance-Gruppe identifizierte eine Reihe von Möglichkeiten, wie Änderungen an der API eingeführt werden können, die für den Benutzer von Vorteil sind und keine breaking change darstellen.
Änderungstyp | Als breaking angesehen? | Grund |
|---|---|---|
Neue Ressource oder Endpunkt | Nein | Beeinflusst bestehende Integrationen nicht |
Neuer optionaler Parameter | Nein | Bestehende Anfragen bleiben gültig |
Neuer optionaler JSON-Schlüssel | Nein | Clients können ihn sicher ignorieren |
Neues Antwortfeld | Nein | Rückwärtskompatibel für Verbraucher |
Neuer erforderlicher Parameter | Ja | Zerstört bestehende Anfragen |
Neuer erforderlicher POST-Schlüssel | Ja | Ungültige bestehende Nutzlasten |
Entfernen eines Endpunkts | Ja | Bestehende Integrationen schlagen fehl |
Ändern des Standardverhaltens | Ja | Ändert erwartete Ergebnisse |
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 breaking change alles, was die Integration eines Benutzers brechen 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-Anfragemethode
Einen wesentlich anderen internen Ablauf eines API-Aufrufs – wie z. B. eine Änderung des Standardverhaltens.
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 Menschen zu unterschiedlichen Zeiten an verschiedenen Endpunkten. Daher ist es sehr wichtig, dass unsere API in der Verwendung von Konventionen konsistent ist. Dies war größer als die Versionierung.
Wir haben eine Governance-Gruppe eingerichtet, die Ingenieure jeder Gruppe, ein Mitglied des Produktmanagement-Teams und unseren CTO umfasst. Diese Gruppe ist dafür verantwortlich, unsere API-Konventionen für alle Teams zu etablieren, zu dokumentieren und durchzusetzen. Auch ein API-Governance Slack-Kanal ist nützlich für lebhafte Diskussionen zu diesem Thema.
Die Governance-Gruppe identifizierte eine Reihe von Möglichkeiten, wie Änderungen an der API eingeführt werden können, die für den Benutzer von Vorteil sind und keine breaking change darstellen.
Änderungstyp | Als breaking angesehen? | Grund |
|---|---|---|
Neue Ressource oder Endpunkt | Nein | Beeinflusst bestehende Integrationen nicht |
Neuer optionaler Parameter | Nein | Bestehende Anfragen bleiben gültig |
Neuer optionaler JSON-Schlüssel | Nein | Clients können ihn sicher ignorieren |
Neues Antwortfeld | Nein | Rückwärtskompatibel für Verbraucher |
Neuer erforderlicher Parameter | Ja | Zerstört bestehende Anfragen |
Neuer erforderlicher POST-Schlüssel | Ja | Ungültige bestehende Nutzlasten |
Entfernen eines Endpunkts | Ja | Bestehende Integrationen schlagen fehl |
Ändern des Standardverhaltens | Ja | Ändert erwartete Ergebnisse |
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 breaking change alles, was die Integration eines Benutzers brechen 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-Anfragemethode
Einen wesentlich anderen internen Ablauf eines API-Aufrufs – wie z. B. eine Änderung des Standardverhaltens.
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 Menschen zu unterschiedlichen Zeiten an verschiedenen Endpunkten. Daher ist es sehr wichtig, dass unsere API in der Verwendung von Konventionen konsistent ist. Dies war größer als die Versionierung.
Wir haben eine Governance-Gruppe eingerichtet, die Ingenieure jeder Gruppe, ein Mitglied des Produktmanagement-Teams und unseren CTO umfasst. Diese Gruppe ist dafür verantwortlich, unsere API-Konventionen für alle Teams zu etablieren, zu dokumentieren und durchzusetzen. Auch ein API-Governance Slack-Kanal ist nützlich für lebhafte Diskussionen zu diesem Thema.
Die Governance-Gruppe identifizierte eine Reihe von Möglichkeiten, wie Änderungen an der API eingeführt werden können, die für den Benutzer von Vorteil sind und keine breaking change darstellen.
Änderungstyp | Als breaking angesehen? | Grund |
|---|---|---|
Neue Ressource oder Endpunkt | Nein | Beeinflusst bestehende Integrationen nicht |
Neuer optionaler Parameter | Nein | Bestehende Anfragen bleiben gültig |
Neuer optionaler JSON-Schlüssel | Nein | Clients können ihn sicher ignorieren |
Neues Antwortfeld | Nein | Rückwärtskompatibel für Verbraucher |
Neuer erforderlicher Parameter | Ja | Zerstört bestehende Anfragen |
Neuer erforderlicher POST-Schlüssel | Ja | Ungültige bestehende Nutzlasten |
Entfernen eines Endpunkts | Ja | Bestehende Integrationen schlagen fehl |
Ändern des Standardverhaltens | Ja | Ändert erwartete Ergebnisse |
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 breaking change alles, was die Integration eines Benutzers brechen 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-Anfragemethode
Einen wesentlich anderen internen Ablauf 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 unser aller (einschließlich unseres eigenen!) Interesse liegt, Änderungen an der API zu verhindern, da die Verwaltung mehrerer Versionen einen erheblichen Mehraufwand darstellt. Wir entschieden uns, dass es ein paar Dinge gab, die wir mit unserer API beheben sollten, bevor wir uns auf „v1“ festlegten.
Das Versenden einer einfachen E-Mail erforderte viel zu viel Aufwand. Um „die einfachen Dinge einfach zu halten“, aktualisierten wir den POST-Körper, um sicherzustellen, dass sowohl einfache als auch komplexe Anwendungsfälle berücksichtigt werden. Das neue Format war auch zukunftssicherer. Zweitens adressierten wir ein Problem mit dem Metrics-Endpunkt. 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, also haben wir jeden group_by in einen separaten Endpunkt aufgeteilt. Schließlich überprüften wir jeden Endpunkt und nahmen hier und da kleine Änderungen vor, um sicherzustellen, dass sie den Standards entsprachen.
Als wir diese Konventionen dokumentierten und diskutierten, kamen wir auch zu dem Schluss, dass es in unser aller (einschließlich unseres eigenen!) Interesse liegt, Änderungen an der API zu verhindern, da die Verwaltung mehrerer Versionen einen erheblichen Mehraufwand darstellt. Wir entschieden uns, dass es ein paar Dinge gab, die wir mit unserer API beheben sollten, bevor wir uns auf „v1“ festlegten.
Das Versenden einer einfachen E-Mail erforderte viel zu viel Aufwand. Um „die einfachen Dinge einfach zu halten“, aktualisierten wir den POST-Körper, um sicherzustellen, dass sowohl einfache als auch komplexe Anwendungsfälle berücksichtigt werden. Das neue Format war auch zukunftssicherer. Zweitens adressierten wir ein Problem mit dem Metrics-Endpunkt. 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, also haben wir jeden group_by in einen separaten Endpunkt aufgeteilt. Schließlich überprüften wir jeden Endpunkt und nahmen hier und da kleine Änderungen vor, um sicherzustellen, dass sie den Standards entsprachen.
Als wir diese Konventionen dokumentierten und diskutierten, kamen wir auch zu dem Schluss, dass es in unser aller (einschließlich unseres eigenen!) Interesse liegt, Änderungen an der API zu verhindern, da die Verwaltung mehrerer Versionen einen erheblichen Mehraufwand darstellt. Wir entschieden uns, dass es ein paar Dinge gab, die wir mit unserer API beheben sollten, bevor wir uns auf „v1“ festlegten.
Das Versenden einer einfachen E-Mail erforderte viel zu viel Aufwand. Um „die einfachen Dinge einfach zu halten“, aktualisierten wir den POST-Körper, um sicherzustellen, dass sowohl einfache als auch komplexe Anwendungsfälle berücksichtigt werden. Das neue Format war auch zukunftssicherer. Zweitens adressierten wir ein Problem mit dem Metrics-Endpunkt. 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, also haben wir jeden group_by in einen separaten Endpunkt aufgeteilt. Schließlich überprüften wir jeden Endpunkt und nahmen hier und da kleine Änderungen vor, um sicherzustellen, dass sie den Standards entsprachen.
Accurate Dokumentation
Es ist wichtig, genaue und nutzbare API-Dokumentation zu haben, um breaking changes, absichtlich oder unabsichtlich, zu vermeiden. Wir haben uns entschieden, einen einfachen API-Dokumentationsansatz zu verwenden und eine Markdown-Sprache namens API Blueprint zu nutzen und unsere Dokumente in Github zu verwalten. Unsere Community trägt zu diesen Open-Source-Dokumenten bei und verbessert sie. Wir pflegen auch einen nicht öffentlichen Satz von Dokumenten in Github für interne APIs und Endpunkte.
Ursprünglich haben wir unsere Dokumente auf Apiary veröffentlicht, ein großartiges Werkzeug zum Prototypisieren und Veröffentlichen von API-Dokumenten. Allerdings funktioniert das Einbetten von Apiary auf unserer Website nicht auf mobilen Geräten, daher verwenden wir jetzt Jekyll, um statische Dokumente zu generieren. Unsere neuesten SparkPost API docs laden jetzt schnell und funktionieren gut auf mobilen Geräten, was wichtig ist für Entwickler, die nicht immer an ihrem Computer sitzen.
Es ist wichtig, genaue und nutzbare API-Dokumentation zu haben, um breaking changes, absichtlich oder unabsichtlich, zu vermeiden. Wir haben uns entschieden, einen einfachen API-Dokumentationsansatz zu verwenden und eine Markdown-Sprache namens API Blueprint zu nutzen und unsere Dokumente in Github zu verwalten. Unsere Community trägt zu diesen Open-Source-Dokumenten bei und verbessert sie. Wir pflegen auch einen nicht öffentlichen Satz von Dokumenten in Github für interne APIs und Endpunkte.
Ursprünglich haben wir unsere Dokumente auf Apiary veröffentlicht, ein großartiges Werkzeug zum Prototypisieren und Veröffentlichen von API-Dokumenten. Allerdings funktioniert das Einbetten von Apiary auf unserer Website nicht auf mobilen Geräten, daher verwenden wir jetzt Jekyll, um statische Dokumente zu generieren. Unsere neuesten SparkPost API docs laden jetzt schnell und funktionieren gut auf mobilen Geräten, was wichtig ist für Entwickler, die nicht immer an ihrem Computer sitzen.
Es ist wichtig, genaue und nutzbare API-Dokumentation zu haben, um breaking changes, absichtlich oder unabsichtlich, zu vermeiden. Wir haben uns entschieden, einen einfachen API-Dokumentationsansatz zu verwenden und eine Markdown-Sprache namens API Blueprint zu nutzen und unsere Dokumente in Github zu verwalten. Unsere Community trägt zu diesen Open-Source-Dokumenten bei und verbessert sie. Wir pflegen auch einen nicht öffentlichen Satz von Dokumenten in Github für interne APIs und Endpunkte.
Ursprünglich haben wir unsere Dokumente auf Apiary veröffentlicht, ein großartiges Werkzeug zum Prototypisieren und Veröffentlichen von API-Dokumenten. Allerdings funktioniert das Einbetten von Apiary auf unserer Website nicht auf mobilen Geräten, daher verwenden wir jetzt Jekyll, um statische Dokumente zu generieren. Unsere neuesten SparkPost API docs laden jetzt schnell und funktionieren gut auf mobilen Geräten, was wichtig ist für Entwickler, 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.
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.
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.
