Zuletzt bearbeitet vor einer Stunde
von Andre Knieschewski

SuperX REST Schnittstelle

REST-Schnittstelle

Die REST-Schnittstelle ist die technische Grundlage, um Funktionen von SuperX nicht nur über klassische Skripte, sondern auch über Weboberflächen und externe Anwendungen bereitzustellen. Sie trennt die eigentliche Verarbeitung von der Darstellung im Browser und macht zentrale Funktionen wie Update, Upgrade oder Statusabfragen über standardisierte HTTP-Aufrufe nutzbar.

Ziel

Das wichtigste Ziel ist eine einfachere und flexiblere Bedienung. Aufgaben, die bisher meist skriptgesteuert auf dem Server ausgeführt wurden, können künftig direkt aus einer Administrationsoberfläche gestartet werden. Dazu gehören zum Beispiel das Aktualisieren von Moduldaten, Modul-Upgrades oder das Anzeigen von Protokollen laufender Jobs.

Vorteile

  • Administrationsaufgaben können über die Weboberfläche ausgeführt werden, ohne direkt auf der Kommandozeile arbeiten zu müssen.
  • Die vorhandenen ETL- und Batch-Prozesse bleiben erhalten und werden lediglich über eine zusätzliche Schnittstelle erreichbar gemacht.
  • Weboberflächen können unabhängig von der eigentlichen Fachlogik gestaltet und weiterentwickelt werden.
  • Hochschulen können Funktionen leichter in eigene Portale oder Webseiten einbinden und dabei ihr eigenes Corporate Design verwenden.
  • Die Schnittstelle kann neben der Weboberfläche auch von Skripten oder anderen Anwendungen genutzt werden.

Einsatzbereiche

Ein erster Einsatzbereich ist die Komponentenverwaltung. Über die REST-Schnittstelle können installierte Module abgefragt, Updates gestartet, Upgrades ausgeführt und Logs angezeigt werden.

Ein weiterer Einsatzbereich sind zukünftige SuperX-Masken. Wenn Maskendefinitionen, Parameter und Ergebnisdaten über die REST-Schnittstelle bereitgestellt werden, kann die Darstellung stärker entkoppelt werden. Dadurch lassen sich Auswertungen flexibler in unterschiedliche Oberflächen integrieren.

Grundidee

Die REST-Schnittstelle ersetzt die vorhandenen Verarbeitungsprozesse nicht. Sie stellt diese Prozesse nur auf einem modernen und einheitlichen Weg bereit. Dadurch können bestehende SuperX-Funktionen schrittweise besser in Weboberflächen, Administrationsseiten und externe Systeme eingebunden werden.


Einrichtung

Dieses Kapitel beschreibt die grundlegenden Schritte, damit die REST-Schnittstelle für die Komponentenverwaltung verwendet werden kann. Die Beschreibung verwendet neutrale Platzhalter und kann dadurch auf unterschiedliche Installationen übertragen werden.

Verwendete Platzhalter

Die folgenden Platzhalter werden in den Beispielen verwendet. Sie müssen jeweils durch die konkreten Pfade der Installation ersetzt werden.

Platzhalter Bedeutung
SUPERX_WEBAPP Verzeichnis der deployten SuperX-Webapp. Dieses Verzeichnis enthält WEB-INF.
SUPERX_GIT Lokales Checkout des SuperX-Git-Repositories.
TOMCAT_WEBAPPS Webapps-Verzeichnis des verwendeten Tomcat.
MODUL_VERZEICHNIS Verzeichnis eines SuperX-Moduls, das in die Komponentenverwaltung eingebunden werden soll.

Beispielhafte Definitionen für eine Shell-Sitzung: 

SUPERX_WEBAPP=/pfad/zur/webapps/superx
SUPERX_GIT=/pfad/zum/superx-git
TOMCAT_WEBAPPS=/pfad/zum/tomcat/webapps
MODUL_VERZEICHNIS=/pfad/zum/modul

Voraussetzungen

Die REST-Schnittstelle ist Teil der SuperX-Webapp. Die Webapp muss daher grundsätzlich lauffähig sein und über den Tomcat erreichbar sein. Erst wenn die normale SuperX-Anwendung erreichbar ist und die Datenbankverbindung funktioniert, sollten die REST-Endpunkte für die Komponentenverwaltung geprüft werden.

Aktuelles Kernpaket verwenden

Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles SuperX-Kernpaket verwendet werden. Bei älteren Kernständen können REST-Endpunkte, Spring-Batch-Konfigurationen oder benötigte Klassen fehlen.

Beispiel für den Download eines Kernpakets: 

wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz

Das Kernpaket wird anschließend in die bestehende Webapp eingespielt. Vorher sollten lokale Anpassungen, kundenspezifische Dateien und projektspezifische Konfigurationen gesichert werden.

Wichtiger Hinweis zum Kern-Upgrade

Bei einem Kern-Upgrade kann es zu Problemen kommen, wenn alte Bibliotheken im Verzeichnis WEB-INF/lib liegen bleiben. Deshalb sollte dieses Verzeichnis vor dem erneuten Entpacken des Kernpakets vollständig geleert werden. 

cd $SUPERX_WEBAPP
rm -f WEB-INF/lib/*

Anschließend wird das neue Kernpaket in die Webapp entpackt. Dadurch ist sichergestellt, dass keine veralteten JAR-Dateien aus einem früheren Kernstand weiterverwendet werden.

Nach dem Upgrade sollten die folgenden Konfigurationsdateien geprüft werden, da sie für REST-Schnittstelle, Datenbankverbindung, Batch-Verarbeitung und Scheduler relevant sind: 

SUPERX_WEBAPP/WEB-INF/classes/spring-batch.properties
SUPERX_WEBAPP/WEB-INF/classes/hikari.properties
SUPERX_WEBAPP/WEB-INF/classes/quartz.properties

Datenbankverbindung prüfen

Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der dbforms-config.xml sollte daher der SpringBeanConnectionProvider verwendet werden. Dieser stellt die Verbindung über die Spring-Konfiguration der Anwendung bereit. 

<dbconnection connectionProviderClass="de.superx.db.SpringBeanConnectionProvider"
              default="true"
              id="datasourceBean"
              isJndi="false"
              isPow2="true"/>

Wenn hier noch eine ältere oder projektspezifische Verbindungsdefinition verwendet wird, kann die REST-Schnittstelle zwar erreichbar sein, aber beim Zugriff auf ETL-Jobs oder Komponenteninformationen fehlschlagen.

Pflichtdatei module_ignore.properties

Die Datei module_ignore.properties muss im Modulverzeichnis der Webapp vorhanden sein. Fehlt diese Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten. 

SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module/module_ignore.properties

Fehlende Kern-ETL-Dateien ergänzen

Für einige Funktionen der Komponentenverwaltung werden zusätzliche ETL-XML-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen. Falls diese Dateien im installierten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git in die Webapp kopiert werden.

Quellverzeichnis im SuperX-Git: 

SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update

Zielverzeichnis in der Webapp: 

SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update

Benötigte Dateien:

  • edustore_kern_man_unload_config_ids.xml
  • edustore_kern_man_unload_config_pg.xml
  • edustore_kern_man_upload_config_ids.xml
  • edustore_kern_man_upload_config_pg.xml

Beispiel zum Kopieren: 

cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_unload_config_ids.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_unload_config_pg.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_upload_config_ids.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/
cp $SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/edustore_kern_man_upload_config_pg.xml $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update/

Modulverzeichnis vorbereiten

Die Komponentenverwaltung liest die verfügbaren Komponenten und ETL-Jobs aus dem Modulbereich der Webapp. Deshalb müssen die benötigten Modulverzeichnisse im Verzeichnis WEB-INF/conf/edustore/db/module erreichbar sein. 

SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module

Falls ein Modulverzeichnis außerhalb der Webapp gepflegt wird, kann es per symbolischem Link eingebunden werden. 

cd $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .

Alternativ kann das Modulverzeichnis auch direkt in das Modulverzeichnis der Webapp kopiert werden. Welche Variante verwendet wird, hängt davon ab, ob die Module zentral gepflegt oder projektspezifisch abgelegt werden.

ETL-Steuerdaten neu einlesen

Nachdem Kern, Modulverzeichnisse und XML-Dateien vorbereitet wurden, müssen die ETL-Steuerdaten neu eingelesen werden. Das erfolgt über die ComponentAdminCLI. Der Aufruf sollte aus dem Tomcat-Webapps-Verzeichnis erfolgen, damit die relativen Pfade zu WEB-INF/classes, WEB-INF/lib und WEB-INF/lib_ext stimmen. 

cd $TOMCAT_WEBAPPS
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" "de.superx.bin.ComponentAdminCLI" -r

Der Parameter -r liest die Komponenten- und Jobdefinitionen neu ein. Danach sollten die Jobs in der REST-Schnittstelle sichtbar sein.

Optional: Einzelnen Job über die CLI testen

Nach dem Einlesen kann ein einzelner Job testweise über die CLI gestartet werden. Dadurch lässt sich prüfen, ob die Jobdefinitionen grundsätzlich funktionieren, bevor die REST-Schnittstelle oder die Weboberfläche verwendet wird. 

cd $TOMCAT_WEBAPPS
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" "de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform

Wenn dieser Aufruf funktioniert, ist die Batch- und ETL-Konfiguration grundsätzlich verwendbar. Fehler an dieser Stelle deuten meistens auf fehlende Moduldateien, fehlerhafte Pfade, fehlende Datenbanktabellen oder eine unvollständige Konfiguration hin.

Optional: Indexproblem beim Einlesen beheben

In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps zu Konflikten mit vorhandenen Indizes kommen. Im Testfall wurde folgender Index entfernt: 

drop index ix_etl_step1;

Dieser Schritt sollte nicht pauschal durchgeführt werden, sondern nur dann, wenn der konkrete Fehler beim Einlesen der ETL-Steps auf diesen Index verweist.

Tomcat neu starten

Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden. Dadurch wird sichergestellt, dass die Webapp alle Klassen und Konfigurationen neu lädt. 

systemctl restart tomcat

Je nach Distribution kann der Dienst auch anders heißen, zum Beispiel tomcat10. 

systemctl restart tomcat10

REST-Schnittstelle prüfen

Nach dem Neustart kann geprüft werden, ob die REST-Schnittstelle erreichbar ist. Die folgenden Aufrufe können direkt im Browser oder mit curl getestet werden.

Komponentenliste: 

https://<<domain>>/superx/ds/api/etl/list

Jobliste aller bekannten Jobs: 

https://<<domain>>/superx/ds/api/etl/job/list

Jobliste eines einzelnen Moduls: 

https://<<domain>>/superx/ds/api/etl/job/list/hrstage

Wenn diese Aufrufe JSON zurückliefern, ist die REST-Schnittstelle grundsätzlich erreichbar. Falls die Aufrufe HTTP 500 liefern, sollten zuerst die Tomcat-Logs, die Datenbankverbindung und das Einlesen der ETL-Steuerdaten geprüft werden.

Erster Funktionstest

Für einen ersten Funktionstest sollte zunächst ein Listenaufruf verwendet werden. Danach kann in einer Testumgebung ein technischer Job gestartet werden.

Beispiel für einen Transform-Aufruf: 

https://<<domain>>/superx/ds/api/etl/transform/hrstage

Beispiel für den Start eines konkreten Jobs: 

https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform

Der Startaufruf liefert im Erfolgsfall eine JobExecutionId zurück. Diese ID kann anschließend zur Status- und Logabfrage verwendet werden.

Statusabfrage: 

https://<<domain>>/superx/ds/api/etl/jobExecutionStatus/{jobExecutionId}

Logabfrage: 

https://<<domain>>/superx/ds/api/etl/jobLog/{jobExecutionId}

Zusammenfassung der Einrichtung

Für eine funktionierende REST-Schnittstelle müssen Kernpaket, Webapp-Struktur, Datenbankverbindung, Modulverzeichnis, module_ignore.properties und ETL-Steuerdaten zusammenpassen. Erst wenn die Komponentenliste und die Jobliste über die REST-API korrekt ausgeliefert werden, sollte die Weboberfläche für die Komponentenverwaltung verwendet werden.

Abgerufen von „https://superxhosting.de/wiki/index.php?title=SuperX_REST_Schnittstelle&oldid=15955“