Hello Leute :).

In diesem Beitrag möchte ich davon berichten wie einfach es sein kann einen Backend REST Server zu erstellen mit zur Hilfenahme von OpenApi Spezifikationen. Mein ultimatives Ziel ist es Backups und den Restore Prozess von Alfresco Daten so einfach wie möglich zu machen. Nach langem recherchieren habe ich mich entschlossen Restic als Backup und Restoring Engine zu benutzen. Da in meinem bisherigen Deployments alle Alfresco Daten, sprich die Blob Daten, DB Daten, Solr Daten usw. im /data Folder vorliegen scheint es der perfekte Use Case für Restic zu sein. Das automatisierte Backup funktioniert so weit gut. Vielen Dank an dieser Stelle lobaro und seiner brillanten restic Backup Arbeit welche mir im Part automatisierte Backup sehr geholfen hat.

Nun steht allerdings noch der Restoring part an. Und wie es scheint gibt es bisher dafür kein Tooling. Der Administrator müsste also immer die Restoring mittel Restic manuell durchführen. Das heißt in die Machine einloggen und die nötigen Restic Restore Befehle ausführen, welche den gewünschten Snapshot wiederherstellen. Diesen Prozess will ich vereinfachen und dem Administrator eine angenehme UI zur Wiederherstellung bereitstellen. Dafür verwende ich die OpenApi Technologien. In den nächsten Abschnitten erzähle ich mehr über OpenApi und was genau ich gemacht habe.

OpenApi

OpenApi welches früher Swagger genannt wurde, ist eine YAML oder JSON Template Sprache zur Beschreibung von RESTful APIs. Folgend beschreibe ich was super an OpenApi ist. Erstens eigenen sich die Templates extrem gut als Dokumentation über die API selber, da aus dem Template eine schick aussehende HTML UI generiert werden kann, welche die API Endpoints sehr gut beschreibt. Eine solche UI ist im Titelbild dieses Blogposts zu sehen. Noch genialer ist die UI kann direkt zum Testen der Endpoints genutzt werden, also zum Senden und Empfangen von Requests und Responses. Viele API Schnittstellen, wie es auch AWS API Gateway eine ist, bieten es and die Parameter Validierung der Requests über OpenApi Files zu machen. Was mit Parametervalidierung gemeint ist versuche ich anhand des folgenden Beispiels zu erklären:

parameters:
    - in: query
    name: userId
    description: Get items of that user
    required: true
    type: string

Hier ist ein Parameter vom Typ Query zu sehen sehen. Das bedeutet dieser würde in der URL in etwa so aussehen

http://<url>/items?userId=martin

Mit der Parametervalidierung kann ich dann bestimmte Eigenschaften des Parameters definieren, wie hier der name userId ob er required ist und welchen Typ der value haben soll, in unserem Fall als vom typ string.

Auch sehr mächtig ist die Eigenschaft, dass es möglich ist aus OpenApi Files Client Libaries und Server Stubs zu generieren. Alfresco generiert zum Beispiel JavaScript Clients mit zur Hilfenahme des API-Explorers (Näheres auf GitHub Api-Explorer) und ADF (oder ADF JS Github). Dort wird zum Beispiel aus dem Swagger File die eine JavaScript API Library erzeugt, welche als Wrapper für die API Requests genutzt werden kann in den ADF Components Github.

Auch cool ist, Postman bietet eine Importierfunktion für OpenApi Files. Dann wird daraus gleich eine Collections erzeugt. Das ist sehr praktisch, wenn man anfangen möchte die Requests in Postman zu schreiben.

Server Generierung

In diesem Teil erzähle ich mehr über meine Implementierung in Github. Der OpenApi Generator ist ein mächtiges Tool zum erzeugen von Client Libs und Server Stubs von OpenApi Spezifikationen wie der bei mir im Repo ./restic.yaml . Zurzeit interessiert mich aber lediglich die Server Stub Generierung. Es kann aus einer Reihe von verschiedenen Server Technologien wie Go, Kotlin, Java, JavaScript ausgewählt werden. Ich habe mich speziell für den NodeJS Express Server entschieden. Um den Server zu generieren wird der folgenden Befehl in ./build_server ausgeführt:

PWD=$(pwd)
docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \
-i /local/restic.yaml \
-g nodejs-express-server \
-o local/server

Ein zusätzlicher Bonus. Der NodeJS Express Server generiert auch eine Swagger UI die dann erreichbar ist auf /api-doc . Da ich bei der Servergenerierung die Handler für die Endpoints nicht immer wieder neue Implementieren möchte, habe ich diese in einem ausgewiesenem Ordner ./handlers untergebracht . Dann muss im OpenApi Spec nur noch drauf verwiesen werden:

operationId: getSnapshots
description: List all snapshots
x-eov-operation-handler: handlers/DefaultController

Das Property x-eov-operation-handler verweist auf die Handlerfunktion. Der ./handlers Ordner muss dann nur noch in die Docker Image kopiert werden.

Testing

Zum Testen verwende ich die neue GitHub Build Engine GitHub Actions bei dem Workflows generiert werden. Ich habe schon in meinem vorherigen Projekt wobeies um einen Let's Encrypt SSL Docker Companion GitHub Actions ausgiebig getestet und für gut empfunden. In meinen Test Workflow unter ./.github/workflows/action.yml wir die Image mittels Docker Compose gestartet und ausgiebig mit zur Hilfenahme von Postman getestet. Falls du dich mehr für automatisierte Tests mit Postman interessierst klick einfach hier

Zusammenfassung

Die Erstellung von REST Servern ist normalerweise ein aufwändiger Prozess, welcher das Schreiben jeder Menge Code benötigt. Es müssen Request Parameter im Path oder Body auf Richtigkeit validiert werden. Oder Url Mapping Algorithmen mit Request und Response Handlerlogiken ausgestattet werden. Und damit der Benutzer des REST Servers nicht verzweifelt sollte die REST API gut dokumentiert sein. All diese Aufgaben und noch viele mehr kann der OpenApi Ansatz lösen.

Mit tollen Arbeiten wie dem OpenApi Generator lassen sich problemlos Rest Server generieren und mittels Swagger HTML UI dokumentieren. Auch kann der REST Server dann problemlos getestet werden zum einen direkt in der Swagger HTML UI mit der try out Funktion und zum anderen können direkt Postman Tests aus dem OpenApi Spec File generiert werden. Die Arbeit mit OpenApi spec is sehr spannen für mich und ich hoffe, ich konnte euch animieren auch mal OpenApi Technologien auszuprobieren. Lasst mich hören wie es bei euch lief!

An die tollen Leser dieses Artikels sei gesagt, dass Feedback jeglicher Art gerne gesehen ist. In Zukunft werde ich versuchen hier eine Diskussionsfunktion einzubauen. Bis dahin sendet mir doch bitte direkten Feedback über meine Sozial Media accounts wie Twitter oder FaceBook. Vielen Dank :).

Ich liebe es an Content Management Open Source Projekte zu arbeiten. Vieles kannst du bereits frei nutzen auf www.github.com/mmuller88 . Wenn du meine dortige Arbeit sowie meine Blog Posts toll findest, denke doch bitte darüber nach, mich zu unterstützen und ein Patreon zu werden:

Werde ein Patreon!

Share