Kurze Zeitreise

Wie bereits zu Beginn erwähnt, geht die Entstehung von OpenAPI auf die Einführung der Swagger-Spezifikation zurück, die ursprünglich Tony Tam im Jahr 2010 entwickelt hat. Swagger entstand aus dem Bedürfnis heraus, eine standardisierte und einfache Möglichkeit zur Beschreibung, Dokumentation und Interaktion mit RESTful-APIs zu schaffen. Die Spezifikation und die damit verbundenen Tools gewannen schnell an Popularität in der Entwicklergemeinschaft.

Im Jahr 2015 wurde die OpenAPI-Initiative (OAI) ins Leben gerufen, um die Weiterentwicklung der Swagger-Spezifikation in einer kollaborativen und branchenübergreifenden Umgebung voranzutreiben. Die OAI wurde von Unternehmen wie Google, IBM, Microsoft, SmartBear Software und weiteren Technologieunternehmen unterstützt.

In der Folge hat die Swagger-Spezifikation unter der Leitung der OpenAPI-Initiative eine Weiterentwicklung erfahren den neuen Namen OpenAPI erhalten. Dies trug dazu bei, die gemeinschaftliche Natur des Projekts widerzuspiegeln. Die Veröffentlichung der ersten Version der OpenAPI-Spezifikation (OpenAPI 2.0) fand im September 2016 statt und basierte auf der damaligen Swagger 2.0-Spezifikation.

Seitdem hat es sich als Standard für die Beschreibung von RESTful-APIs etabliert und ist durch kontinuierliche Weiterentwicklung und Zusammenarbeit in der Industrie gewachsen. Die neueren Versionen brachten eine Reihe von Verbesserungen und neue Funktionen im Vergleich zu OpenAPI 2.0. Darunter eine bessere Unterstützung für JSON-Schema, verbesserte Modularität und erweiterte Möglichkeiten zur Beschreibung von API-Endpunkten sowie Datenmodellen.

Wie funktioniert OpenAPI?

Grundlagen

OpenAPI definiert eine standardisierte, sprachagnostische Schnittstelle, um RESTful-APIs auf eine maschinenlesbare Weise zu beschreiben. Diese Beschreibung enthält Informationen über die verfügbaren Endpunkte, die unterstützten Operationen (wie GET, POST, PUT, DELETE) (Siehe auch CRUD), die möglichen Rückgabewerte und viele weitere Details. Es verwendet das YAML- oder JSON-Format, um diese Beschreibungen auf leicht verständliche und bearbeitbare Weise zu präsentieren.

Vorteile

Standardisierung:

Es bietet eine einheitliche und standardisierte Methode zur Beschreibung von RESTful-APIs. Dadurch gewährleistet bzw. verbessert man die Interoperabilität zwischen verschiedenen Systemen und Technologien.

Dokumentation:

OpenAPI-Dokumente dienen als lebendige Dokumentation der API, die immer auf dem neuesten Stand ist. Dies erleichtert die Zusammenarbeit zwischen verschiedenen Teams und reduziert die Wahrscheinlichkeit von Fehlern und Inkonsistenzen.

Generierung von Code und Client-Bibliotheken:

Durch die maschinenlesbare Natur der Spezifikation können Entwickler automatisch Code-Stubs, Server-Implementierungen und Client-Bibliotheken in verschiedenen Programmiersprachen generieren.

API-Design und -Validierung:

Es ermöglicht Entwicklern, ihre API-Designs frühzeitig zu validieren und Inkonsistenzen zu identifizieren, bevor sie in die Implementierung einfließen.

Interaktive API-Explorer:

Man kann OpenAPI-Dokumente in interaktive API-Explorer, wie z. B. Swagger UI, importieren, um APIs auf benutzerfreundliche Weise zu erkunden und zu testen.

Ökosystem

Das Ökosystem umfasst zahlreiche Tools und Lösungen, die Entwickler bei der Arbeit mit der Spezifikation unterstützen. Einige der bekanntesten Tools sind:

Swagger:

Swagger ist eine Sammlung von Tools, die Entwicklern helfen, ihre APIs zu entwerfen, zu dokumentieren und zu testen. Dazu gehören unter anderem Swagger Editor, Swagger Codegen und Swagger UI.

ReDoc:

ReDoc ist eine Open-Source-Lösung zur Erstellung von API-Dokumentationen auf Basis von OpenAPI-Dokumenten. Es bietet eine übersichtliche und ansprechende Darstellung der API-Dokumentation, die für Endbenutzer leicht zugänglich ist.

Postman:

Postman ist ein weit verbreitetes API-Entwicklungstool, das die Unterstützung für OpenAPI-Spezifikationen bietet. Es ermöglicht Entwicklern, APIs zu entwerfen, zu testen, zu dokumentieren und zu überwachen, indem sie die OpenAPI-Dokumente importieren und mit den integrierten Tools interagieren.

API-Lebenszyklus

Der Einsatz von OpenAPI erstreckt sich über den gesamten API-Lebenszyklus:

Planung:

Entwickler können OpenAPI verwenden, um das API-Design zu skizzieren und Einigkeit über die Funktionsweise und Struktur der API zu erzielen.

Entwicklung:

Mit automatisch generierten Code-Stubs und Client-Bibliotheken auf Basis der Spezifikation können Entwickler schnell und effizient an der Implementierung arbeiten.

Testen:

Es ermöglicht das einfache Erstellen von Testfällen und das automatisierte Testen von APIs auf Kompatibilität und Konformität mit der Spezifikation.

Dokumentation:

Die lebendige Dokumentation auf Grundlage von OpenAPI-Dokumenten stellt sicher, dass API-Benutzer immer auf dem neuesten Stand der API-Funktionalität sind.

Deployment:

Man kann OpenAPI-Dokumente für die automatische Bereitstellung und Konfiguration von APIs auf verschiedenen Plattformen und Umgebungen verwenden.

Überwachung und Wartung:

Damit generierte Tests und Überwachungstools kann man die API-Performance überwachen und Wartungsmaßnahmen effizient durchgeführen.

Alternative API-Spezifikationen

Daneben gibt es noch andere API-Spezifikationen wie RAML (RESTful API Modeling Language) und API Blueprint. Alle drei Spezifikationen haben ähnliche Zielsetzungen, unterscheiden sich jedoch in Syntax, Tool-Unterstützung und Popularität. OpenAPI ist derzeit die am weitesten verbreitete Spezifikation und eine Vielzahl von Organisationen sowie Entwickler bevorzugen es.

Fazit:

OpenAPI ist eine leistungsstarke und flexible Spezifikation, die Entwicklern hilft, RESTful-APIs zu entwerfen, zu erstellen und zu dokumentieren. Es bietet eine standardisierte, sprachunabhängige Schnittstelle und unterstützt den gesamten API-Lebenszyklus von der Planung bis zur Überwachung. Mit einem reichhaltigen Ökosystem an Tools und Lösungen hat es seine Stellung als führende API-Spezifikation im heutigen schnelllebigen Technologieumfeld gefestigt.

Der Beitrag OpenAPI – Die Brücke für nahtlose Kommunikation und effiziente Integration von Web-Services erschien zuerst auf CEOsBay.

Kurze Zeitreise

Bis zum Aufkommen der Microservice-Architekturen wurde Software klassischerweise als Monolith entworfen. Dabei gab es keinerlei interne Schnittstellen, da alle Informationen im Monolithen weitergereicht werden konnten. Dementsprechend konnte man sich im Testing nur auf die Stufen Unittests, Integrationstests und End-to-End-Tests konzentrieren. Mit dem Aufkommen der Microservice-Architekturen existiert nun eine Vielzahl an internen Schnittstellen und damit entsteht die Notwendigkeit, diese zu testen. Die Kommunikation der Services untereinander geschieht dabei nicht zufällig, sondern folgt klar definierten Regeln, den sogenannten Schnittstellen-Contracts.

Was ist Contract Testing?

Wie bereits angesprochen, wurde die korrekte Zusammenarbeit von API und Consumer meist durch Integrationstests sichergestellt. Da diese allerdings eine lauffähige Systemlandschaft benötigen, können Fehler erst relativ spät erkannt werden. Bei der Entwicklung ist es jedoch von Vorteil, das Feedback so früh wie möglich zu erhalten. Hinzu kommt, dass Integrationstests eigentlich zum Prüfen der Fachlichkeit dienen. In heutigen Testlandschaften stellen sie strenggenommen „nur nebenher“ fest, wenn es technische Probleme an der Schnittstelle gibt. Das kann sowohl bedeuten, dass der Aufwand bei der Fehlersuche steigt, weil neben fachlichen Problemen auch technische Ursachen zum Fehlschlag des Tests führen können, als auch der Wartungsaufwand der Tests sich erhöht.

Macht also Sinn, dedizierte Tests zu nutzen, um Fehler an Schnittstellen zu finden. Hier bietet sich Contract Testing, genauer gesagt, Consumer Driven Contract Testing (CDCT) an. Verträge für Softwarekomponenten. Der Zusatz „Consumer Driven“ bedeutet, der Consumer bestimmt den Vertrag (Aus diesem Grund nennt man es auch Consumer Contract) und das sich die API nach dessen Vorgaben richten muss.

Neben Consumer Contracts gibt es die etwas verbreiteteren Provider Contracts wie WSDL-/XML-Schemata von SOAP-APIs oder Werkzeuge wie Swagger im Kontext von REST-Services.

Auch wenn sich die Funktionsweise von Framework zu Framework unterscheidet, bleibt die Idee dahinter gleich. Der Provider erfüllt den vom Consumer definierten Vertrag.

Der Vertrag enthält die API samt Parameter und die erwartete (minimale) Antwort. Dabei kann die Beschreibung der Parameter durch den Einsatz von regulären Ausdrücken beliebig präzise sein. So kann der Consumer erwarten, beim Aufruf der API einen unbestimmten String-Parameter oder einen bestimmten String-Parameter aus einem vordefinierten Set zu übergeben. Der zweite Fall ist äußerst hilfreich, wenn der Provider diesen String-Parameter in einen Enum-Wert übersetzt.

Der Consumer Test mit Pact

Sämtliche Verträge zwischen dem Consumer und dem Provider werden in einer JSON-Datei, auch Pact-Datei genannt, definiert. Der Consumer generiert diese Pact-Datei beim Ausführen seiner Pact-Tests und veröffentlicht sie auf dem Pact-Broker. Bei den Tests handelt es sich um gewöhnliche Unit-Tests und sie basieren auf einem der vielen von Pact unterstützen Test-Frameworks wie JUnit oder Jest. In dem Test ruft der Consumer die zu testende API inklusive Parameter auf. Der Aufruf wird von einem Mock-Provider, der vom Pact-Framework zur Verfügung gestellt wird, entgegengenommen. Der Mock-Provider prüft, ob dieser Aufruf mit dem Aufruf aus dem Vertrag übereinstimmt. Sind keine Abweichungen gefunden, antwortet der Mock-Provider mit der minimalen Antwort, die ebenfalls aus dem Vertrag stammt. Der Consumer empfängt in seinem Test die Antwort und vergleicht sie mit seiner Erwartung. Stimmen sie überein, ist der Test erfolgreich. Auf diesem Weg stellt der Pact-Test sicher, dass der Consumer den Aufruf tätigen und die Antwort verarbeiten kann.

Der Pact-Broker ist ein Webserver, der sowohl vom Consumer als auch vom Provider erreichbar sein muss. Er verwaltet die Verträge, indem er sie versioniert ablegt, sie dem Provider zur Verfügung stellt und die Testergebnisse speichert. Die Art und Weise wie der Consumer die Verträge auf dem Pact-Broker veröffentlicht, ist abhängig von der eingesetzten Programmiersprache der Tests und/oder dem eingesetzten Dependendency-Management. Für Maven beispielsweise gibt es ein spezielles Pact-Plugin, das den publish-Goal anbietet, für JavaScript existiert hingegen eine spezielle Pact-Version mit dem Namen Pact-js.

Der Provider Test

Analog zum Consumer-Test ist der Provider-Test auch ein Unit-Test und wird im Rahmen der restlichen Unit-Tests ausgeführt. Hierbei werden alle Verträge, die der Provider mit seinen Consumern abgeschlossen hat, vom Pact-Broker heruntergeladen. Der Aufruf der APIs erfolgt lokal, sodass ein Aufruf durch den Consumer simuliert wird. Der Provider verarbeitet den Aufruf und generiert seine Antwort, die mit der erwarteten Antwort aus dem Vertrag verglichen wird. Sollten sie gleich sein, hat der Provider den Pact-Test bestanden. Ansonsten gilt der Test als fehlgeschlagen und das Artefakt des Providers kann nicht ordnungsgemäß gebaut werden. Die Ursache für Fehlschläge sind in den meisten Fällen Code-Änderungen am Provider ohne den Consumer entsprechend angepasst zu haben oder die Erwartungshaltung des Consumers ist fehlerhaft. In beiden Fällen wird durch CDCT ein Missstand aufgedeckt, der erst zur Laufzeit bemerkbar gewesen wäre.

Alternativen zu Pact

Natürlich ist Pact nicht das einzige Framework zum Implementieren von CDCT, wenn auch aktuell eines der am weitesten verbreiteten. Neben Pact existieren noch ein paar weitere Möglichkeiten für das vertragsbasierte Testen wie Postman, Spring Cloud Contract Project oder Dredd, auf die ich noch in zukünftigen Beiträgen eingehen werde. Aus diesem Grund erfolgt auch das Fazit erst, wenn ich ein paar Vergleiche aufstellen kann.

Der Beitrag Pact.io – Für die nahtlose Integrationstestautomatisierung durch Contract Tests erschien zuerst auf CEOsBay.