Andrek: REST Doku

2026-06-25T14:31:00Z

REST Doku

Neue Seite

=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.

{| class="wikitable"
!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:

<source lang="bash">
SUPERX_WEBAPP=/pfad/zur/webapps/superx
SUPERX_GIT=/pfad/zum/superx-git
TOMCAT_WEBAPPS=/pfad/zum/tomcat/webapps
MODUL_VERZEICHNIS=/pfad/zum/modul
</source>

===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:

<source lang="bash">
wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz
</source>

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.

<source lang="bash">
cd $SUPERX_WEBAPP
rm -f WEB-INF/lib/*
</source>

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:

<source lang="text">
SUPERX_WEBAPP/WEB-INF/classes/spring-batch.properties
SUPERX_WEBAPP/WEB-INF/classes/hikari.properties
SUPERX_WEBAPP/WEB-INF/classes/quartz.properties
</source>

===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.

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

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.

<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module/module_ignore.properties
</source>

===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:

<source lang="text">
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>

Zielverzeichnis in der Webapp:

<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
</source>

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:

<source lang="bash">
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/
</source>

===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.

<source lang="text">
SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module
</source>

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

<source lang="bash">
cd $SUPERX_WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
</source>

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.

<source lang="bash">
cd $TOMCAT_WEBAPPS
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" "de.superx.bin.ComponentAdminCLI" -r
</source>

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.

<source lang="bash">
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
</source>

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:

<source lang="sql">
drop index ix_etl_step1;
</source>

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.

<source lang="bash">
systemctl restart tomcat
</source>

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

<source lang="bash">
systemctl restart tomcat10
</source>

===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:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/list
</source>

Jobliste aller bekannten Jobs:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/job/list
</source>

Jobliste eines einzelnen Moduls:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/job/list/hrstage
</source>

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:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/transform/hrstage
</source>

Beispiel für den Start eines konkreten Jobs:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/job/execute/eduetl/hrstage_load_and_transform
</source>

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

Statusabfrage:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/jobExecutionStatus/{jobExecutionId}
</source>

Logabfrage:

<source lang="text">
https://<<domain>>/superx/ds/api/etl/jobLog/{jobExecutionId}
</source>

===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.

SuperX REST Schnittstelle - Versionsgeschichte

Andrek: REST Doku