Automated REST-Api Code Generation: Wie IT-Systeme miteinander sprechen.

REST steht für Representational State Transfer. Dieser Architektur-Ansatz beschreibt, wie verteilte Systeme miteinander sprechen können. Denn auch Softwaresysteme stehen auf eine gepflegte Kommunikation.

Wir erklären anhand eines Beispiels mit Shopware 6.2.3., warum es sich für uns immer öfter lohnt, neue Wege zu beschreiten. Keine Angst vor neuen Tools! Denn oft machen sie uns effizienter. 

Wir standen vor Kurzem bei einem Projekt vor einer altbekannten Aufgabe:

• Einerseits: Ein Backend mit REST-APIs, mehr oder minder gut dokumentiert. Im konkreten Fall handelte es sich hierbei um Shopware 6.2.3.
• Andererseits: Ein komplett selbst entwickeltes React-Frontend, das eben diese APIs nutzen soll.

Wir haben uns die aktuelle Shopware 6 Dokumentation zu Gemüte geführt und festgestellt, dass die von uns benötigten Funktionen erstens auf verschieden APIs aufgeteilt sind und zweitens noch immer diversen Updates und Wandlungen unterliegen. Hinzu kommt, daß es im Frontend natürlich entsprechende API-Zugriffsklassen sowie Model-Klassen geben muss. Und aus der Erfahrung wussten wir, dass gerade das Erstellen der Model-Klassen mit erheblichem Zeitaufwand verbunden ist. Dazu kommt die Gefahr, Dinge zu vergessen. Doch:

Wie es der Zufall so will, stolperten wir im Zuge unserer Recherchen über eine automatisch generierte OpenAPI 3.0 Definition der Shopware APIs. Eine spannende Chance, denn: Endlich konnten wir ein Automatisierungstool verwenden! Wie genau?

Nach einiger Suche und Vergleichen der Dokumentationen kristallisierte sich ein interessantes Produkt heraus: Der OpenAPI Generator in der aktuellen Release-Version 4.3.1. Ein Vorteil des Tools: Der Generator war eine breite Unterstützung zum Erzeugen von API ClientsServer-Komponenten in einer wirklich langen Liste von Sprachen, auch wenn wir uns vorerst nur für den TypeScript-Client interessierten.
 

1. Prüfung: Um das Tool und seinen Einsatz für die aktuellen Aufgaben zu prüfen und auch einzusetzen, extrahierten wir zuerst die OpenAPI 3.0 Spezifikation der Sales Channel API von Shopware.

2. Installation: Danach wurde der Generator lokal installiert. Bemerkenswert ist die Vielfalt. Direkt über Bash, via NPM, Homebrew oder Docker, es bleibt kaum ein Wunsch offen und dauert in der Regel etwa eine Minute.
    

Ein simpler Aufruf wie

openapi-generator generate -g typescript-fetch -o /var/www/output -i api.yaml

erzeugt dann im Verzeichnis /var/www/output/ weitere Verzeichnisse mit den API-Zugriffsklassen und Modellen für Typescript. Bei rund 15 APIs mit einer Größenordnung von 40 und mehr Modellen ist das eine Menge Ersparnis. Die Anzahl der Modelle ergibt sich übrigens aus den Requests und Responses, welche möglichst genau definiert werden sollten.

Es empfiehlt sich den Elementen, besonders Objekten, klar erkennbare Namen zu geben. Ansonsten werden Modelle mit automatisierten Namen wie InlineResponse2005 vergeben, was der Verwendbarkeit und Wiedererkennbarkeit des erzeugten Codes zuwider läuft und bei späteren Updates auf Grund von einer erneuten Nummerierung der Modelle zu Konflikten und Fehlern führen kann.

Zur Qualität des erzeugten Codes ist zu sagen, daß er mit wenigen Ausnahmen sogleich verwendet werden kann. Linter zur Qualitätskontrolle sollte man trotzdem ausschließen, da der Code so gut wie keinen Guidelines entspricht. Des weiteren enthält die Datei runtime.js eine JS-Variable, die es nicht mehr gibt und daher Fehler verursacht. Außerdem werden anyOf, none und ähnliche Instruktionen aus dem OpenAPI File in teilweise unmögliche TypeScript-Konstrukte mit komplett falscher Syntax übersetzt. Eine moderne IDE sollte hier aber sofort die entstandenen Probleme anzeigen.

Sobald diese Fehler behoben waren, war die API von Client-Seite aus bereits einsatzbereit und konnte beispielsweise ausden Stores direkt aufgerufen werden.

Funktionell haben die gut leserlich gestalteten API-Zugriffsklassen allerdings einige interessante Dinge zu bieten. So werden zum Beispiel Header- und Authentifizierungsmechanismen auf dem OpenAPI File übernommen. So können Tokens oder auch OAuth-Pfade in einem einfachen Konfigurationsfile hinterlegt werden.

Das vorhandene Middleware-Interface, dass uns Zugriff auf die internen Funktionen vor und nach dessen Ausführung erlaubte, konnten wir nutzen, um den für dieses Projekt notwendige Authentifizierungsmechanismus anzupassen.

Aktuell steht auch eine Beta der Version 5.0 zur Verfügung. Und wie angekündigt hat sich die – zumindest die für Typescript überprüfte – Codequalität erheblich verbessert. Einwandfreies transpillen nach ECMAScript war kein Problem mehr! Man darf also durchaus gespannt sein, was uns bis zum finalen Release noch erwartet.

Der Aufwand zur Erstellung einer gute definierte API im OpenAPI Format ist mit etwas Übung überschaubar und meiner Meinung nach sogar zwingend notwendiger Teil der Gesamtdokumentation eines derartigen Projektes. Und ganz bestimmt ist sie die saubere Grundlage zur automatischen Code-Generierung!