Teilen Sie:
){kind=small}
Alyssa is a writer and editor specializing in technology and the software development space. She lives in central California with her husband, kids, and three rescue dogs.
OpenAPI-geführte Entwicklung bei Nexmo
Lesedauer: 3 Minuten
Bei Nexmo haben wir einen OpenAPI-basierten Entwicklungsprozess eingeführt. Hier ist der Grund dafür.
Die Geschichte hat uns gelehrt, dass die Softwareentwicklung unter dem Gewicht überzogener Spezifikationen erstickt.
Andy Hunt, Mitverfasser des Agilen Manifests, erzählt die Geschichte von einem Projekt, an dem er in den 1990er Jahren arbeitete. Nach zweieinhalb Jahren und mehreren Millionen Dollar hatte der Projektarchitekt einen Raum voller UML-Diagramme erstellt, aber nicht eine einzige Codezeile wurde implementiert.
Heute balancieren wir sorgfältig die Notwendigkeit von Vorab-Spezifikationen mit dem Verständnis, dass wir die wahre Natur des Problems, das wir lösen, oft erst beim Schreiben des Codes selbst entdecken.
Es hat sich jedoch herausgestellt, dass das Gleichgewicht zwischen Spezifikationen und Entdeckung bei öffentlichen APIs anders ist als bei der Entwicklung anderer Arten von Software. Das hat uns bei Nexmo dazu veranlasst, die Art und Weise, wie wir neue APIs entwickeln, zu ändern: Das erste, was wir bei der Entwicklung eines neuen Dienstes tun, ist, eine OpenAPI-Spezifikation zu erstellen. Das bringt uns Vorteile in Bezug auf die Erfahrung der Entwickler, die Lesbarkeit für Menschen und Maschinen, die Automatisierung und vieles mehr.
APIs sind öffentliche Verträge. Wenn wir etwas wie unsere Messages APIentwickeln und auf den Markt bringen, gehen wir einen Vertrag mit unseren Kunden ein: Wenn Sie API-Aufruf X mit Daten Y tätigen, wird unsere Plattform Z tun.
Damit ist die Entwicklung einer öffentlichen API im Wesentlichen dasselbe wie die Erstellung einer Norm. Denken Sie an SVG. Es ist ein Standard für Vektorgrafiken. Der Standard und die verschiedenen Implementierungen dieses Standards existieren als getrennte Dinge. Wenn ich eine Bibliothek schreibe, die SVG-Dateien erzeugt, dann sollte ich mich nicht um die Implementierungsdetails der Software kümmern müssen, die diese Datei später lesen wird.
Allzu oft werden APIs durch die zugrunde liegende Implementierung geformt, was Joel Spolsky als undichte Abstraktionen-oder durch spontane Designentscheidungen. Wenn wir mit der Erstellung einer OpenAPI-Spezifikation beginnen, können wir bewusste Design-Entscheidungen treffen, die einen Schritt entfernt sind von den Details, die darunter liegen. Das wiederum führt zu einer konsistenten, intuitiven Entwicklererfahrung.
Ein unerwarteter Vorteil ist, dass die Erstellung von OpenAPI-Spezifikationen potenzielle Probleme bei der Benutzerfreundlichkeit aufdeckt. Wir haben festgestellt, dass, wenn es schwierig ist, eine API in einer OpenAPI-Spezifikation zu modellieren, dies in der Regel auch bedeutet, dass die API selbst schwer zu verwenden ist. Das hat uns dazu veranlasst, einige nicht optimale API-Entwürfe zu überdenken, die es sonst vielleicht in die Produktion geschafft hätten.
Taylor Barnett von Stoplight.io beschreibt die OpenAPI-Spezifikationen als "einen Entwicklungsvertrag, eine Brücke zwischen Teams." Auch wenn Menschen den Code schreiben, fungieren APIs ausdrücklich als Schnittstellen zwischen Maschinen.
Durch die OpenAPI-spezifische Entwicklung wird die API zu viel mehr als nur der Schnittstelle zwischen zwei Code-Bits. Sie macht die API zu einer Quelle der Verständigung zwischen Menschen. Technische Redakteure können sie nutzen, um ihre Dokumentationsbemühungen in Gang zu bringen, Entwicklervertreter können sie externen Entwicklern erklären, und Produktmanager können sie als Quelle der Wahrheit über die API-Fähigkeiten pflegen.
Wie von Kin Lane dokumentiertdokumentiert, veröffentlichen Unternehmen zunehmend ihre OpenAPI-Spezifikationen auf GitHub als öffentliche Erklärung zum Design einer API. Mit einem einzigen Dokument können wir eine maschinen- und menschenlesbare Erklärung abgeben, wie sich die API verhalten soll. Von dort aus können Entwickler sehen, welches Verhalten erwartet wird, und über die Fähigkeiten der API nachdenken.
Die OpenAPI-Spezifikationen versprechen, alle Arten von Automatisierung zu ermöglichen. Es besteht die Möglichkeit, automatisch Client-Bibliotheken, Mock-Endpunkte, Tests und Dokumentation zu erstellen.
Screenshot of API
Bei Nexmo befinden wir uns am Anfang dieser Reise. Heute generieren wir automatisch API-Referenzdokumente und einige Tests. Insbesondere haben wir festgestellt, dass eine OpenAPI-Spezifikation im Vorfeld die Erstellung von Smoke-Tests erleichtert hat.
Unsere OpenAPI-Spezifikationen definieren die erwarteten Eingaben und Ausgaben der API, einschließlich Fehlermeldungen. Wir können diese Spezifikation verwenden, um automatisch Smoke-Tests zu generieren, die absichtlich falsche Daten bereitstellen und dann prüfen, ob die erwartete Fehlermeldung zurückgegeben wird.
Der größte Vorteil ist, dass wir mit einer OpenAPI-Spezifikation beginnen und damit eine einzige Quelle der Wahrheit haben. Anstatt API-Entwürfe in verschiedenen Formaten und an verschiedenen Orten (Wikis, Google Docs usw.) zu haben, ist die Spezifikation jetzt einfach ein Standardteil des Entwicklungsprozesses und wird mit Standardentwicklungswerkzeugen erstellt.
Mit dieser einen Spezifikation können wir uns und unseren Kollegen mitteilen, wann die Entwicklung abgeschlossen ist, und externen Entwicklern mitteilen, was sie erwarten können. In gewissem Sinne ist die Spezifikation die API und die Implementierung ist genau das.
Wir befinden uns am Anfang unserer OpenAPI-First-Reise. Bislang haben wir den Prozess mit zwei APIs getestet -Redact und Geheimes Managementaber alle unsere APIs haben vollständige, öffentliche OpenAPI-Spezifikationen und wir planen, unsere gesamte Entwicklung auf das Spec-First-Modell umzustellen.
Nach unserer bisherigen Arbeit sind wir sicher, dass dies zu qualitativ hochwertigeren API-Implementierungen, Zeitersparnis und einem besseren Verständnis führen wird. Wir sind gespannt, wie dies die Qualität von APIs in der gesamten Branche verbessern wird.