Zum Thema OpenAPI gibt es eine ganze Reihe Artikel und Seiten im Netz. Warum sollte ich also einen weiteren schreiben? Ganz einfach. Viele dieser Artikel richten sich an (erfahrene) Webentwickler. Was ist aber mit all denjenigen, die sich bisher mit EDI oder dem Austausch von elektronischen Geschäftsnachrichten beschäftigt haben? Dieser kurze Einstieg ist für Euch.
APIs zum Austausch von Geschäftsdokumenten
Eine API als Verbindungsstück zwischen zwei Systemen oder Softwarekomponenten an sich ist nichts Neues. Deren Anwendung für den Austausch von Geschäftsdokumenten aber schon. Für diese Anforderung gibt es seit vielen Jahrzehnten Lösungen für den elektronischen Geschäftsdatenaustausch. Beispiele sind das klassische EDI auf Basis von EDIFACT oder der Austausch von XML-Dateien. Letztere erfährt gerade im Zug der verpflichtenden Einführung elektronischer Rechnungen für öffentliche Auftraggeber eine stärkere Verbreitung.
Doch gerade hier zeigen sich auch die Probleme der bisherigen Lösungen. Klassischer Dokumentenaustausch ist prinzipiell nichts anderes als die digitale Nachbildung der Papierwelt. Also hat sich im Grunde genommen in den letzten 100 Jahren kaum etwas am Grundprinzip geändert. Nur das Übertragungsmedium hat sich geändert: von Papier zu einem von vielen elektronischen Formaten. Das ging so lange gut, wie die zu übertragenden Dokumente nur zwischen zwei Partnern ausgetauscht wurden. Zum Beispiel die Rechnung vom Verkäufer zum Käufer.
Durch die fortschreitende Digitalisierung verbunden mit der Globalisierung steigen jedoch die Anforderungen. Oftmals sind am Austausch der Informationen nicht nur zwei, sondern mehr Partner interessiert, zum Beispiel, wenn Waren grenzüberschreitend transportiert werden sollen. Dann kommen neben den klassischen Partnern auch noch die ein- und die ausführende Zollbehörde, das Transportunternehmen und ggf. noch weitere Partner hinzu. Folglich ist dies eine sehr heterogene Welt in Bezug auf die Technik. Und gleichzeitig steigt die Anforderung nach Transparenz in der Lieferkette. Und die Forderung Produktpiraterie und -fälschungen besser erkennen und verhindern zu können.
Mit klassischem EDI ist das kaum umsetzbar
Doch warum ist das mit klassischem EDI so schwierig umzusetzen? Sicherlich spielt dabei eine wesentliche Rolle, dass es nicht “Das EDI” gibt, sondern viele verschiedene Standards zum Austausch von Geschäftsdokumenten. Diese sind teilweise durch Anforderungen einer Branche oder individuelle Anforderungen einzelner Unternehmen noch zusätzlich beladen. Dadurch wird ein Standard oftmals so stark verwässert, dass es viele hundert Varianten einer einzelnen Nachricht geben kann. Darüber hinaus kommt noch erschwerend dazu, dass hier die Anforderungen an “Geschäftsdokumente” erfüllt werden sollen.
Doch diese Anforderungen kommen aus der Papierwelt. Einer Welt, in der Menschen das erhaltene (Papier-) Dokument mit den Büchern (Buchhaltung) abgleichen. Diese Dokumente enthalten außerdem sehr viele Informationen, die in einem elektronischen Prozess eigentlich überflüssig sein könnten.
So braucht zum Beispiel eine Zollbehörde nicht die kompletten Vertragsbeziehungen einschließlich Lieferbedingungen oder vereinbarten Konditionen zu kennen. Klassisch entstehen hierfür wiederum neue Dokumente und neue (EDI -) Nachrichten. Oder beteiligte Personen oder Systeme haben (noch) keinen einheitlichen elektronischen Zugriff auf die Informationen. Heute kündigen große Lieferanten und ihren Kunden Lieferungen elektronisch an (Despatch advice). Und dennoch wird zusätzlich ein Lieferschein oder Warenbegleitschein ausgedruckt und der Sendung beigefügt.
Für eine EDI-Umsetzung müssen also die Prozesse der einzelnen Organisationen entlang der Wertschöpfungsketten auch semantisch ineinandergreifen. Also müssen auch die Managementsysteme der Organisationen mit solchen elektronischen Nachrichten umgehen können. Und immer auf einem gleichen Stand sein. Das ist in der Praxis nur schwer zu erreichen. Standards helfen dabei, aber eine Umsetzung ist oftmals zu schwierig und zu teuer.
Wer cloud meine Daten?
Noch ein weiterer Aspekt kommt hinzu. Eine Studie aus dem Jahr 2020 hat gezeigt, dass eines der größten Hemmnisse die Angst ist, durch zentrale Datenaustauschplattformen die Kontrolle über die eigenen Daten zu verlieren.
Die Sicherung der Datensouveränität ist also ein wesentlicher Aspekt, wenn im Business-to-Business Bereich Plattformen neu geschaffen werden sollen.
REST APIs bieten hier einen klaren Ansatz, sich von den Geschäftsdokumenten für den Datenaustausch zu lösen. Stattdessen werden nur die tatsächlich benötigten Informationen ausgetauscht. Mit klar definierten Partnern. So kann zum Beispiel sichergestellt werden, dass keine vereinbarten Preise über ein Lieferantenportal in die falschen Hände gelangen.
Trennung von Datenstrukturen und Services
Ein klassisches EDI Szenario umfasst im Wesentlichen nur zwei Services. Die Umwandlung von Daten eines Quellsystems in das Datenformat des Zielsystems und die Weiterleitung der Daten an das Zielsystem. Natürlich kann es komplexere Szenarien mit Rückmeldungen geben, die ähnlich wie ein Einschreiben mit Rückschein funktionieren. Aber alles, was darüber hinausgeht, ist eigentlich nicht mehr Bestandteil des eigentlichen EDI-Szenarios. Die Prozesse selbst müssen von den jeweiligen Endsystemen erbracht werden, zum Beispiel wird eine Auftragsbestätigung zu einer Bestellung vom System des Verkäufers erstellt. Die EDI-Lösung überträgt diese dann wiederum zurück. Also wiederum mit denselben Services, jedoch einem anderen Dokument.
In der Welt der APIs geht der Servicegedanke darüber hinaus. Eine API kann aktiv einzelne Prozessschritte unterstützen. Oder sie kann auch echten Mehrwert bieten, wie zum Beispiel die Bereitstellung von Informationen, wobei der API-Nutzer festlegen kann, welche Filterkriterien dabei angewendet werden sollen. Dies ist in der klassischen EDI-Welt kaum denkbar.
Diese Möglichkeiten führen dazu, dass in einer API nicht nur die Datenstrukturen definiert sind, sondern auch die Services. Diese verwenden dann die definierten Datenstrukturen, um eingehende Informationen zu verarbeiten, oder ausgehende Informationen bereitzustellen.
Machen APIs nicht alles komplizierter?
Puh, das klingt ziemlich kompliziert. Und wenn jetzt noch mehr dazu kommt, wird es dann nicht noch unübersichtlicher? Und irgendjemand muss es ja auch noch implementieren!
Genau hier setzt OpenAPI an. Gerade keine proprietären Regeln zu entwickeln, sondern die Spezifikation einer API zu standardisieren. Diesen Unterschied zu verstehen, ist immens wichtig. Es geht also nicht darum, wie eine API implementiert wird. Nein, sondern darum, was sie genau leisten soll. Welche Services sie bietet und welche Datenstrukturen sie dabei unterstützt.
Wie oben beschrieben gibt es im EDI-Umfeld viele Standards, auch internationale. Das Zentrum der Vereinten Nationen für Handelserleichterungen und elektronische Geschäftsprozesse UN/CEFACT standardisiert bereits seit vielen Jahren die Bedeutungen von Datenstrukturen bei Geschäftsdokumenten. UN/CEFACT veröffentlicht semantische Referenzdatenmodelle, an denen sich weltweit viele Organisationen und Branchen orientieren.
Von Bedeutungen und Zwillingen
REST APIs werden im Internet bereits viele Jahre eingesetzt. Vor allem zur Bereitstellung von Dienstleistungen für andere Webseiten oder auf mobilen Geräten. Beispiele sind APIs zur Währungsumrechnung oder die diversen Karten-APIs, mit der man einfach von A nach B navigieren kann. Das semantische Web spielt dabei ebenfalls eine wichtige Rolle. Die Systeme der Onlineshops, Suchmaschinen und sozialen Netzwerke sollen semantische Zusammenhänge erkennen können. Zum Beispiel welche Zutaten ein Rezept benötigt, wie lange die Zubereitung dauert, und welche Shops diese Zutaten zu welchen Preisen anbieten.
Eine wesentliche Grundlage dafür bieten die Standards auf schema.org. An diesen klaren Definitionen orientieren sich all diese Dienste und ermöglichen es sogenannte digitale Zwillinge (Digital Twins) abzubilden. Alles Identifizierbare der realen Welt lässt sich auch digital abbilden: Personen, Veranstaltungen, Häuser, Lizenzen, Software, Produkte und Dienstleistungen, um nur einige zu nennen. Und das Ganze verständlich für Menschen und durch Maschinen verarbeitbar.
Kein Wunder also, dass viele sich die Frage gestellt haben, wie sich dies auf die Business-to-Business-Ebene übertragen lässt, auch UN/CEFACT. Wie bleiben die Errungenschaften der letzten Jahrzehnte mit Web-APIs erhalten?
OpenAPI – Ein Spezifikationsstandard für APIs
Der Spezifikationsstandard OpenAPI definiert also ein Regelwerk, wie APIs zu spezifizieren sind. Welche Services werden bereitgestellt? Welche Datenstrukturen werden benötigt? Was sind die Anforderungen an eine Implementierung? Und das Ganze sowohl in einer Version, die durch den Entwickler gelesen werden kann, aber auch durch eine Maschine.
Genau hier liegt die eigentliche Stärke dieses Standards. Der sehr große Support durch eine Vielzahl an Tools und Programmierumgebungen. Damit ist es möglich, eine API auf der Fachebene zu definieren. Mit all ihren Services und Datenstrukturen. Sie kann gleichzeitig beschrieben werden, so dass ein Entwickler diese möglichst intuitiv umsetzen kann.
Und dabei wird der Entwickler massiv unterstützt. Da die Spezifikation maschinenlesbar ist, existieren Tools, die direkt aus der Spezifikation Quellcode erzeugen. Damit ist sichergestellt, dass die spezifizierten Eigenschaften der Schnittstelle selbst korrekt implementiert sind: Die Namen von Endpunkten (Services) sind korrekt. Die von diesen verwendeten Datenstrukturen sind korrekt umgesetzt und auch alle Rückgabewerte klar definiert.
Natürlich muss der Entwickler noch die eigentliche Implementierung der Server- bzw. Clientseite vornehmen. Stellt er sich dabei geschickt an, kann diese Implementierung sogar sicher gegenüber künftigen Änderungen sein. Eine Aktualisierung der Spezifikation kann direkt in den Sourcecode übernommen werden und bedarf nur kleinerer Anpassungen.
Wer definiert OpenAPI?
OpenAPI hat seinen Ursprung in Swagger. Bereits im Jahr 2010 hat der Hersteller von Swagger, die Firma SmartBear erkannt, dass eine API Spezifikation nur dann erfolgreich sein kann, wenn sie offen und gemeinschaftlich (community-driven) entwickelt wird. Daher hat sie die Rechte an die OpenAPI Initiative übertragen. Zu dieser gehören durchaus große Namen wie Google, Microsoft, SAP, Bloomberg und IBM. Diese Community ist sehr aktiv und entwickelt die Spezifikation stetig weiter. Die zum Zeitpunkt dieses Artikels jüngste Veröffentlichung ist OpenAPI 3.1.
Spätestens seit dem Jahr 2016 steht also Swagger nur noch für die von der Firma SmartBear erstellten Tools. Die mit diesen Tools erstellten Spezifikationen sind in der Regel OpenAPI Spezifikationen. Allerdings unterstützten diese Tools auch noch die alten Vorgängerformate, insbesondere das Format Swagger 2.0.
Nutzung und Verbreitung von OpenAPI
Das TMForum führt regelmäßig Studien zur Verbreitung von OpenAPI durch. Die letzte Studie zeigt eine deutliche Zunahme an Adoptionen. Vermehrt umkleiden Unternehmen ihre bestehenden APIs in OpenAPI Spezifikationen, sobald diese zum unternehmensübergreifenden Datenaustausch dienen. Gemäß der Studie teile sich der Markt insbesondere in zwei Lager auf: Klare Vertreter von OpenAPI und solche Organisationen, die sich künftig verstärkt um OpenAPI kümmern wollen.
In der Vorstellung von OpenAPI 3.1 erklärte Darrel Miller von Microsoft, dass es auch noch viele Implementierungen mit RAML gäbe. Jedoch zeige der Trend, dass RAML mehr bei Inhouse-Lösungen zu finden ist. OpenAPI bildet dabei vermehrt die Grundlage für unternehmensübergreifende Szenarien.
Code-First (Swagger) oder Model-First (GEFEG.FX)?
Ein wesentlicher Unterschied bei den derzeit auf dem Markt vorhandenen Tools liegt darin, ob die Quellcodeentwicklung oder die modellbasierte Entwicklung im Vordergrund steht. Der Swagger-Editor ist ein typisches Beispiel für eine Code-First-Anwendung. In einem Editor kann der API-Entwickler direkt seine API-Spezifikation erfassen und dokumentieren. Dies umfasst sowohl die Servicestrukturen, als auch die Datenstrukturen. Neben diesem maschinenlesbaren Format sieht er auch gleich die aufbereitete Dokumentation für einen anderen Entwickler. Die Dokumentation steht dann zum Beispiel in einem Developer-Portal zur Verfügung.
Im Gegensatz dazu verfolgt die Lösung GEFEG.FX einen Modell-getriebenen Ansatz. Nicht der technische Entwickler, sondern der Fachanwender steht hier im Vordergrund. Er ist verantwortlich für die betriebswirtschaftliche Sicht und die Prozesse in der Organisation oder zwischen den Organisationen. Oftmals ist er mit den bestehenden EDI-Implementierungen vertraut, oder er kennt zumindest die (wirtschaftlichen und rechtlichen) Anforderungen an die umzusetzenden Prozesse. Mit diesem Wissen ist er in der Lage die vorhandenen semantischen Referenzmodelle und Standards bei der API-Spezifikation zu verwenden. Das Rad wird nicht jedes Mal neu erfunden. Ändert sich ein solcher Standard, übernimmt GEFEG.FX die Änderung einfach in die API-Spezifikation. Zeitgleich werden die Governance-Anforderungen smart umgesetzt, ohne die einzelnen Abteilungen zu sehr einzuschränken. Dafür spielt es keine Rolle, ob es um die Umsetzung der elektronischen Rechnung, des elektronischen Lieferscheins, EDI, die Konsumgüterindustrie, die Automobilindustrie, die Branche der Energieversorger, UN/CEFACT oder andere geht.
Meine Empfehlung
Der Code-First Ansatz ist perfekt für Web-Entwickler. Fachanwender sind damit aber überfordert. Daher gibt es von mir die klare Empfehlung an all diejenigen mit Schwerpunkt EDI oder dem Austausch von elektronischen Geschäftsnachrichten: Plant OpenAPI als Model-First-Ansatz. Das ist zukunftssicher, erweiterbar und anpassbar.
