OpenAPI in der Praxis (1) Apps mit API und Dokumentation ausstatten

Anbieter zum Thema

netfiles GmbH

Eine App ohne API? Kaum noch zeitgemäß, aber grundsätzlich lässt sich eine API mit etwas Fleißaufwand nachrüsten.

Ohne API sieht eine Anwendung heute schnell alt aus, insbesondere im Netz. Meistens wird eine REST-API basierend auf der OpenAPI-Spezifikation verwendet. Dies bietet die Vorzüge eines weit verbreiteten und offenen Standards. Doch wie integriert man die API in eine Anwendung?

Man kann mit Fug und Recht behaupten, dass wir in API-Zeiten leben. (Professionelle) Anwender erwarten mittlerweile, dass sie Funktionalität bekommen, die sie nicht über einen einzigen, starren, vorgegebenen Workflow nutzen müssen. Per API lassen sich eigene Clients erstellen und vor allem Workflows automatisieren.

Das Ganze geht so weit, dass nicht wenige Entwickler (und API-Tooling-Anbieter) mit einem API-First-Ansatz an ihre Projekte herangehen: API definieren und Tools erstellen, dann Prototypen passender Server- und Client-Anwendungen – so viel zur Theorie, doch in der Praxis ist es manchmal nicht ganz so simpel.

Für das Grundverständnis ist aber eigentlich der umgekehrte Fall interessant: Eine Anwendung existiert bereits und nun soll eine API her. Das wollen wir in diesem zweiteiligen Artikel Stück für Stück durchexerzieren. An einem Beispiel, das so nah wie möglich an einer reinen Hello-World-Anwendung ist. Die einzige Ausgangsbasis ist eine winzige SQL-Datenbank.

Die REST-API wird natürlich mittels OpenAPI umgesetzt. Das Schöne daran ist, dass sich über die erstellte Spezifikation eine (beinahe) vollautomatische Dokumentation erstellen lässt, und zwar samt Code-Beispielen für ganz konkrete Anwendungsfälle.

Bevor Sie sich mit der Praxis beschäftigen, sollten Sie freilich mit den Begrifflichkeiten vertraut sein, die hier ständig auftauchen: OpenAPI, Swagger, ReDoc, Redocly und zudem Smartbear. Was es damit auf sich hat, welche Funktionen dahinter stecken und warum gerade Swagger und OpenAPI häufig durcheinandergewürfelt werden, haben wir bereits in einem Artikel erläutert.

Automatische API-Dokumentation

Swagger und OpenAPI im Einsatz

Das Projekt im Überblick

Die Ausgangsbasis soll hier eine kleine SQL-Datenbank sein. Der eigentliche Inhalt spielt keine Rolle. Das Layout beschränkt sich auf drei Spalten in einer einzigen Tabelle. Eine App um die Datenbank herum existiert nicht – es handelt sich schließlich um eine datenzentrische Schnittstelle. Zudem sollen sich Apps schließlich später über die API selbst entwickeln lassen.

Im nächsten Schritt muss aus der Datenbankstruktur die OpenAPI-Spezifikation erstellt werden – das eigentliche Herz des ganzen Prozederes. Hierbei handelt es sich um eine YAML-Datei.

Die YAML-Datei dient dazu, eine Server-App zu erstellen, die die API anbietet und entsprechend CRUD-Operationen (Create, Read, Update, Delete) für die Datenbank ermöglicht.

Letztlich wird die YAML-Spezifikation erneut genutzt, um die Dokumentation via ReDoc zu erstellen.

Dabei ist es nicht unwichtig zu erwähnen, dass es sich dabei um einen von vielen Wegen handelt! Das Tooling-Angebot rund um OpenAPI ist gigantisch. Leider finden sich darunter auch etliche verwaiste Tools, ältere Helferlein, die nie von der OpenAPI-Version 2.0 auf die aktuelle 3er aktualisiert worden sind und Programme, die speziell und auch komplex sind. Hier soll es um das Verständnis gehen und dabei ist Einfachheit hilfreich.

Apropos Tooling – hier kommen einige Programme zum Einsatz:

• Xampp: Entwicklungsumgebung für das Web, inklusive Datenbankverwaltung mit phpMyAdmin.

• ChatGPT: Zum Konvertieren und für Demo-Code – mit ein wenig manueller Nachsorge schneller als viele spezielle Tools

• Redocly CLI: Kommandozeilen-Tool zum Erstellen und Verwalten einer OpenAPIbasierten Dokumentation.

• Flask: Python-Framework, das besonders einfache Server-Apps ermöglicht.

• Node.js/npm

• Swagger-Editor: Prüfen der YAML-Spezifikation, automatisches Erstellen von Apps.

Und damit sich die vielen Namen und Konzepte schon mal mit etwas Leben füllen, hier ein Bild der finalen Redoc-Dokumentation – ein Anblick, den einige bereits kennen:

Die Datenbank als Ausgangspunkt

Der Begriff EDV verschwindet langsam aus dem allgemeinen Wortschatz. Dennoch zeigt der Begriff, worum es bei Anwendungen und in der IT generell geht – das Verarbeiten von Daten. Also ist eine Datenbasis, hier in Form einer Datenbank, ein guter Start. Über Xampp und das darin enthaltene phpMyAdmin wird hier eine möglichst simple Datenbank „Useful Things“ angelegt, mit gerade einmal drei Spalten: Thing, Owner, Usages, wobei die Things-Spalte auch als Index fungiert.

Inhalt benötigt die Datenbank nicht, zum Testen sollten aber ein paar Datensätze eingepflegt werden, um die API vernünftig testen zu können. Wichtig ist aber das Datenbank-Schema, also die Struktur. Und diese lässt sich exportieren.

Simple Datenbank in phpMyAdmin

Dieses Schema dient nun als Basis für die OpenAPI-Spezifikation. Dafür gibt es zum Beispiel spezialisierte Werkzeuge aus dem Fundus der OpenAPI Tools bei GitHub.

Da es sich dabei um eine Standardaufgabe handelt, können Sie diese Konvertierung auch getrost einem KI-Helfer anvertrauen. ChatGPT hat hier beispielsweise auf Anhieb eine korrekte, wenn auch unvollständige API-Definition erstellt und auf Nachfrage dann auch vervollständigt.

Das heißt im Wesentlichen: Zu jeder Spalte der Tabelle gibt es in der Definition so genannte Pfade mit Angaben zur Verarbeitung. Ein Pfad ist dann zum Beispiel ein Konstrukt wie „/useful_things“ für die ganze Tabelle oder „/useful_things/{name}“, um Einträge nach Namen zu finden. Zu den Pfaden gesellen sich dann die Angaben zu den CRUD-Operationen, umgesetzt über Requests via GET, POST, PUT und DELETE. Zudem bekommen alle definierten Requests auch mögliche Responses zugeteilt, sprich 200-Antworten für erfolgreiche Anfragen und 404-Antworten für fehlgeschlagene.

Hier als Beispiel die GET- und POST-Operationen für den Pfad „/useful_things“:

Neben den Pfaden enthält die YAML-Datei noch Metainformationen wie die Beschreibung der Datenbank, einen oder mehrere Server und so weiter.

Doch hierbei gilt es Vorsicht zu bewahren, denn generative KIs wie ChatGPT neigen dazu Standards „aufzubohren“. In unserem Fall hat die KI „x-db-user“ und „x-db-server“ mit den Verbindungsdaten zur Datenbank eingefügt. Diese dienen rein der Information und gehören nicht zum OpenAPI-Standard.

Und damit ist der wichtigste Schritt auch schon getan – Sie haben Ihre API bereits! Beim API-First-Ansatz hätten Sie mit dieser YAML-Definition begonnen und hätten daraus dann umgekehrt ein Schema zum Anlegen einer Datenbank erzeugen können.

Nun geht es nur noch darum, die API zu implementieren, so dass die definierten Pfade/Operationen auch tatsächlich mit der Datenbank kommunizieren.

Eigentlich könnte und sollte der Weg ab hier einfach sein: Der Swagger-Editor bietet die Möglichkeit, nicht nur ad hoc die interaktive API-Oberfläche Swagger GUI zu sichten, sondern auch echten, lauffähigen Code für Server- und Client-Anwendungen zu generieren – die sogenannten Stubs.

Die Stubs sollen dann als Basis für echte Apps dienen. Ein wenig eigene Entwicklungsleistung wird schon erwartet. Allerdings funktionieren diese Stubs leider nicht immer sofort und neigen dazu so komplex zu sein, dass es einige Einarbeitung erfordert.

Wir verzichten daher darauf und implementieren die API im nächsten Schritt in Form einer winzigen Python-Anwendung über das Flask-Framework.

OpenAPI in der Praxis: Ausblick auf Teil 2

Für die Demo-Implementierung sorgen Python und das Framework Flask. Die automatische Dokumentation wird im ReDoc-Format per CLI-Tool erstellt.

"OpenAPI in der Praxis (2): Datenbank um API und Dokumentation erweitern" folgt am Mo., 21.10.24 ab 12:30 Uhr.

OpenAPI in der Praxis (2)

Datenbank um API und Dokumentation erweitern

(ID:50156501)