REST-Schnittstelle
Ab dem SuperX-Kernmodul 6.0 steht eine REST-Schnittstelle zur Verfügung, über die zentrale Funktionen von SuperX auch über Weboberflächen, Skripte und externe Anwendungen angesprochen werden können.
Die REST-Schnittstelle ergänzt die bestehenden SuperX-Funktionen. Vorhandene ETL-, Batch- und Maskenprozesse werden dabei nicht ersetzt, sondern über HTTP-Endpunkte zusätzlich erreichbar gemacht.
Zu den wichtigsten Einsatzbereichen gehören:
- Komponentenverwaltung und ETL-Jobs
- Status- und Protokollabfragen
- SuperX-Masken und deren Eingabefelder
- Ausführung von Masken und Abruf der Ergebnistabellen
- Export von Berichtsergebnissen
- Einbindung von SuperX-Funktionen in eigene Weboberflächen
In den folgenden Beispielen wird diese Beispielinstallation verwendet:
https://demo.superx-testserver.de/superx/
Bei einer eigenen Installation müssen lediglich Domain und gegebenenfalls der Kontextpfad angepasst werden.
Grundlagen
Die REST-Endpunkte befinden sich unterhalb von:
https://demo.superx-testserver.de/superx/ds/api/
Die Schnittstelle liefert überwiegend JSON zurück. Lesende Aufrufe werden in der Regel mit HTTP GET ausgeführt. Einige Funktionen benötigen HTTP POST, insbesondere das Ausführen von SuperX-Masken.
Die REST-Schnittstelle verwendet die normale SuperX-Authentifizierung. Wird sie aus einer bereits angemeldeten Browser-Sitzung aufgerufen, kann die vorhandene Session verwendet werden.
Einrichtung und Voraussetzungen
Die REST-Schnittstelle ist Bestandteil des Kernmoduls 6.0 und der SuperX-Webapp. Eine separate REST-Anwendung muss nicht installiert werden.
Voraussetzung ist zunächst eine grundsätzlich funktionierende SuperX-Installation:
- die SuperX-Webapp ist über Tomcat erreichbar,
- die Datenbankverbindung funktioniert,
- ein aktueller Kernstand ist installiert,
- die benötigten Modulverzeichnisse sind eingebunden,
- die ETL- und Jobdefinitionen wurden eingelesen.
Aktuelles Kernpaket verwenden
Für die REST-Schnittstelle und die Komponentenverwaltung sollte ein aktuelles Kernpaket ab Kern 6.0 verwendet werden.
Beispiel:
wget https://super-ics.de/superx/dist/kern6.0b_superx_utf8_POSTGRES_patch.tar.gz
Bei einem Kern-Upgrade sollte darauf geachtet werden, dass keine veralteten Bibliotheken aus einem älteren Kernstand in WEB-INF/lib liegen bleiben.
Vor Änderungen sollten lokale Anpassungen und projektspezifische Konfigurationen gesichert werden.
Nach einem Upgrade sollten insbesondere folgende Dateien geprüft werden:
WEB-INF/classes/spring-batch.properties
WEB-INF/classes/hikari.properties
WEB-INF/classes/quartz.properties
Datenbankverbindung prüfen
Die REST-Schnittstelle verwendet die Datenbankverbindung der Webapp. In der dbforms-config.xml sollte der SpringBeanConnectionProvider verwendet werden:
<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 grundsätzlich erreichbar sein, aber beim Zugriff auf Komponenten, Jobs oder Masken fehlschlagen.
module_ignore.properties prüfen
Für die Komponentenverwaltung muss folgende Datei vorhanden sein:
WEB-INF/conf/edustore/db/module/module_ignore.properties
Beispielinhalt:
ignore.modules=kennx,gxstage,bil
Fehlt die Datei, können beim Einlesen der Komponenten oder beim Aufruf der Komponentenliste Fehler auftreten.
Modulverzeichnisse bereitstellen
Die Komponentenverwaltung liest verfügbare Komponenten und ETL-Jobs aus:
WEB-INF/conf/edustore/db/module
Modulverzeichnisse können direkt dort abgelegt oder per symbolischem Link eingebunden werden.
Beispiel:
cd $WEBAPP/WEB-INF/conf/edustore/db/module
ln -s $MODUL_VERZEICHNIS .
Zusätzliche Kern-ETL-Dateien prüfen
Für einzelne Funktionen der Komponentenverwaltung werden zusätzliche ETL-Dateien benötigt, insbesondere für das Entladen und Wiedereinspielen von Konfigurationen.
Quellverzeichnis im SuperX-Git:
SUPERX_GIT/superx/WEB-INF/conf/edustore/db/install/conf/his1/edustore_update
Zielverzeichnis in der Webapp:
$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
Falls diese Dateien im verwendeten Kernpaket noch fehlen, müssen sie aus dem SuperX-Git ergänzt werden.
ETL-Steuerdaten einlesen
Nach Änderungen an Kern, Modulverzeichnissen oder Jobdefinitionen müssen die ETL-Steuerdaten neu eingelesen werden.
Beispiel:
cd $WEBAPP
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.
Alternativ kann dafür auch der entsprechende REST-Endpunkt verwendet werden:
https://demo.superx-testserver.de/superx/ds/api/etl/job/writeJobsToDb
Einzelnen Job über die CLI testen
Wenn unklar ist, ob ein Fehler in der REST-Schnittstelle oder bereits in der ETL-Konfiguration liegt, kann ein einzelner Job testweise direkt über die CLI gestartet werden.
Beispiel:
cd $WEBAPP
java -classpath "./superx/WEB-INF/classes/:./superx/WEB-INF/lib/*:./superx/WEB-INF/lib_ext/*" \
"de.superx.bin.ComponentAdminCLI" -e hrstage_load_and_transform
Funktioniert der Job bereits über die CLI nicht, sollten zunächst Moduldateien, Pfade, Datenbanktabellen und ETL-Konfiguration geprüft werden.
Tomcat neu starten
Nach Änderungen an Bibliotheken, Klassen, Spring-Konfigurationen oder Moduldateien sollte Tomcat neu gestartet werden.
Beispiel:
systemctl restart tomcat10
Je nach Installation kann der Dienst auch anders heißen.
REST-Schnittstelle prüfen
Nach der Einrichtung sollten zunächst einfache Listenaufrufe getestet werden:
https://demo.superx-testserver.de/superx/ds/api/etl/list
https://demo.superx-testserver.de/superx/ds/api/etl/job/list
Wenn beide Aufrufe JSON zurückliefern, ist die REST-Schnittstelle für die Komponentenverwaltung grundsätzlich erreichbar.
Für Masken kann zusätzlich ein einfacher Formularaufruf getestet werden:
https://demo.superx-testserver.de/superx/ds/api/form/71030
Fehlersuche bei der Einrichtung
Bei Problemen sollten insbesondere folgende Punkte geprüft werden:
| Problem | Prüfung |
|---|---|
| REST-Endpunkt liefert HTTP 500 | Tomcat-Log prüfen, Datenbankverbindung und Spring-Konfiguration kontrollieren. |
| Komponentenliste ist leer oder fehlerhaft | Modulverzeichnis und module_ignore.properties prüfen.
|
| Jobs fehlen | ETL-Steuerdaten mit ComponentAdminCLI -r oder über /etl/job/writeJobsToDb neu einlesen.
|
| Job funktioniert über REST nicht | Denselben Job testweise über die CLI starten und Tomcat-Log prüfen. |
| Spezialjobs fehlen | Zusätzliche ETL-XML-Dateien im Verzeichnis edustore_update prüfen.
|
| REST-Aufruf funktioniert nach einem Upgrade nicht | Bibliotheken in WEB-INF/lib sowie spring-batch.properties, hikari.properties und quartz.properties prüfen.
|
| POST auf eine Maske liefert "Required request body is missing" | Einen JSON-Body mitsenden, mindestens {}.
|
| POST liefert "application/octet-stream is not supported" | Header Content-Type: application/json setzen.
|
In einzelnen Testumgebungen kann es beim Einlesen der ETL-Steps außerdem zu Konflikten mit vorhandenen Datenbankindizes kommen. Ein solcher Eingriff sollte nur vorgenommen werden, wenn die konkrete Fehlermeldung darauf verweist.
Komponentenverwaltung und ETL
Über die ETL-Schnittstelle können Komponenten angezeigt, Jobs ermittelt und Verarbeitungsläufe gestartet oder überwacht werden.
Der Basis-Pfad lautet:
https://demo.superx-testserver.de/superx/ds/api/etl
Übersicht der wichtigsten ETL-Aufrufe
Die in der Tabelle angegebenen Aufrufe sind relativ zu der Basis-URL. Ein vollständiger Aufruf sieht zum Beispiel so aus:
https://demo.superx-testserver.de/superx/ds/api/etl/list
| Funktion | Methode | Aufruf | Zweck |
|---|---|---|---|
| Komponenten anzeigen | GET | ds/api/etl/list
|
Liefert die bekannten beziehungsweise installierten SuperX-Komponenten mit technischen Informationen. |
| Installierbare Komponenten | GET | ds/api/etl/installables/list
|
Zeigt Komponenten, die grundsätzlich installiert werden können. |
| Alle ETL-Jobs | GET | ds/api/etl/job/list
|
Liefert alle bekannten ETL- und Batch-Jobs. |
| Jobs einer Komponente | GET | ds/api/etl/job/list/hrstage
|
Zeigt nur die Jobs einer bestimmten Komponente. |
| Jobdetails | GET | ds/api/etl/job/hrstage_load_and_transform
|
Liefert technische Informationen zu einem bestimmten Job. |
| Jobdefinitionen neu einlesen | GET | ds/api/etl/job/writeJobsToDb
|
Liest die vorhandenen Jobdefinitionen erneut in die Datenbank ein. |
| Job starten | GET | ds/api/etl/job/execute/eduetl/hrstage_load_and_transform
|
Startet einen bestimmten Job und liefert eine JobExecutionId zurück. |
| Installation starten | GET | ds/api/etl/job/install/hrstage
|
Startet die Installation einer Komponente. |
| Upgrade starten | GET | ds/api/etl/job/upgrade/hrstage
|
Startet ein Upgrade einer installierten Komponente. |
| Alle Upgrades starten | GET | ds/api/etl/job/upgrade_all
|
Startet beziehungsweise verarbeitet anstehende Upgrades mehrerer Komponenten. |
| Komponente deinstallieren | GET | ds/api/etl/job/uninstall/hrstage
|
Startet die Deinstallation einer Komponente. |
| Unload starten | GET | ds/api/etl/unload/hrstage
|
Startet den Unload einer Komponente. |
| Transform starten | GET | ds/api/etl/transform/hrstage
|
Startet die Transformation bereits vorhandener Daten. |
| Complete starten | GET | ds/api/etl/complete/hrstage
|
Startet modulabhängige Abschlussarbeiten. |
| Installationsfunktionen | GET | ds/api/etl/installFunctions/hrstage
|
Zeigt zusätzliche Installationsfunktionen einer Komponente. |
| Laufende Jobs | GET | ds/api/etl/running
|
Zeigt aktuell laufende Jobs. |
| Jobstatus | GET | ds/api/etl/jobExecutionStatus/12345
|
Liefert den aktuellen Status einer Jobausführung. |
| Joblog | GET | ds/api/etl/jobLog/12345
|
Liefert das Protokoll einer Jobausführung. |
| Jobausführungen | GET | ds/api/etl/jobExecutionInfos
|
Liefert Informationen zu Jobausführungen. |
| Job stoppen | GET | ds/api/etl/stop/12345
|
Stoppt eine bestimmte Jobausführung. |
| Job starten oder fortsetzen | GET | ds/api/etl/start/12345
|
Spricht eine vorhandene Jobausführung erneut an. |
| Alle Jobs stoppen | GET | ds/api/etl/job/stopAll
|
Stoppt alle laufenden Jobs. |
Typischer ETL-Ablauf
Eine Anwendung sollte die verfügbaren Jobs möglichst nicht fest hinterlegen, sondern dynamisch über die REST-Schnittstelle ermitteln.
Ein typischer Ablauf für ein Modulupdate ist:
1. Komponenten laden
/etl/list
2. Jobs des Moduls laden
/etl/job/list/hrstage
3. Gewünschten Job starten
/etl/job/execute/eduetl/hrstage_unload_load_transform
4. Jobstatus abfragen
/etl/jobExecutionStatus/12345
5. Jobprotokoll anzeigen
/etl/jobLog/12345
Der Start eines Jobs liefert normalerweise eine JobExecutionId. Diese ID wird anschließend für Status- und Logabfragen verwendet.
Spezialjobs wie beispielsweise
kern_unload_config_special
kern_upload_config_special
können ebenfalls über den generischen Execute-Endpunkt gestartet werden.
SuperX-Masken und Berichte
Auch SuperX-Masken können über die REST-Schnittstelle angesprochen werden. Dadurch lassen sich Maskendefinitionen, Eingabefelder und Ergebnisdaten unabhängig von der klassischen SuperX-Oberfläche verwenden.
Als Beispiel wird im Folgenden die Maske mit der TID 71030 verwendet.
Übersicht der wichtigsten Masken- und Berichtsaufrufe
Die in der Tabelle angegebenen Aufrufe sind relativ zu der Basis-URL. Ein vollständiger Aufruf sieht zum Beispiel so aus:
https://demo.superx-testserver.de/superx/ds/api/form/71030
| Funktion | Methode | Aufruf | Zweck |
|---|---|---|---|
| Maskenaufbau laden | GET | ds/api/form/71030
|
Liefert die Eingabefelder der Maske mit Feldtypen, Defaultwerten, Auswahllisten und weiteren Eigenschaften. |
| Abhängige Felder aktualisieren | POST | ds/api/form/71030/inputupdate
|
Berechnet abhängige Maskenfelder nach Änderung eines Eingabefeldes neu. |
| Informationen zur Maske | GET | ds/api/report?tid=71030
|
Liefert Metadaten der Maske wie TID, Name, Beschreibung und Sachgebiet. |
| Maske ausführen | POST | ds/api/report?tid=71030
|
Führt die Maske aus und liefert die Ergebnistabelle als JSON. |
| Ergebnis-Stylesheets | GET | ds/api/report/stylesheets?tid=71030
|
Zeigt die für die Maske verfügbaren Ergebnis-Stylesheets. |
| Sichten eines Feldes | GET | ds/api/report/views?tid=71030&fieldName=Institution
|
Liefert die verfügbaren Sichten beziehungsweise Hierarchien eines Maskenfeldes. |
| Inhalt einer Sicht | GET | ds/api/report/view?tid=71030&fieldName=Institution&viewId=...
|
Liefert den Inhalt einer bestimmten Sicht. |
| Bericht herunterladen | POST | ds/api/report/download?tid=71030
|
Erzeugt einen Export des Berichtsergebnisses. |
| Themenbaum | GET | ds/api/menu/tree
|
Liefert den für den angemeldeten Benutzer sichtbaren SuperX-Themenbaum. |
| Teil des Themenbaums | GET | ds/api/menu?tid=71030
|
Liefert einen bestimmten Bereich des Themenbaums. |
Masken verwenden
Der Aufruf
https://demo.superx-testserver.de/superx/ds/api/form/71030
liefert unter anderem:
- Namen der Eingabefelder
- Feldtypen
- Beschriftungen
- Pflichtfelder
- Defaultwerte
- Auswahllisten
- Baum- beziehungsweise TreeSelect-Inhalte
- verfügbare Stylesheets
Damit kann eine eigene Oberfläche die Eingabemaske dynamisch aufbauen.
Zum eigentlichen Ausführen einer Maske wird der Report-Endpunkt mit HTTP POST verwendet:
POST https://demo.superx-testserver.de/superx/ds/api/report?tid=71030
Der Request benötigt:
Content-Type: application/json
Auch wenn keine Maskenparameter gesetzt werden sollen, muss ein gültiger JSON-Body mitgegeben werden:
{}
Sollen Felder gesetzt werden, werden diese über den JSON-Body übergeben.
Beispiel:
{
"Kennung": "admin",
"Gruppe": "",
"Name": "",
"Institution": ""
}
Die Antwort enthält die Ergebnistabelle als JSON.
POST-Aufruf im Browser testen
GET-Aufrufe können direkt über die Adresszeile des Browsers getestet werden.
Für POST-Aufrufe kann beispielsweise in Firefox die Netzwerkanalyse verwendet werden:
- Entwicklertools mit F12 öffnen.
- Netzwerkanalyse auswählen.
- Einen REST-Aufruf markieren und Bearbeiten und erneut senden auswählen.
- Methode von GET auf POST ändern.
- Header ergänzen:
Content-Type: application/json
- Unter Inhalt mindestens folgenden JSON-Body eintragen:
{}
- Anfrage senden.
Ein korrekt übertragener leerer JSON-Body führt beispielsweise zu:
Content-Type: application/json
Content-Length: 2
Typische Fehler:
| Fehler | Ursache | Lösung |
|---|---|---|
Required request body is missing
|
Der POST-Request enthält keinen Body. | Mindestens {} als Inhalt mitsenden.
|
Content-Type 'application/octet-stream' is not supported
|
Der Body wird ohne passenden Content-Type übertragen. | Content-Type: application/json setzen.
|
Hinweise zur Verwendung
REST-Endpunkte können abhängig von ihrer Funktion Daten verändern oder umfangreiche Verarbeitungsläufe starten. Insbesondere Installation, Upgrade, Deinstallation und ETL-Jobs sollten daher nur für entsprechend berechtigte Benutzer verfügbar sein.
Für eigene Weboberflächen empfiehlt es sich, Komponenten, Jobs und Masken dynamisch über die REST-Schnittstelle zu ermitteln. Dadurch müssen neue Module, Spezialjobs oder zusätzliche Masken nicht fest in der Oberfläche hinterlegt werden.
Für die Komponentenverwaltung sind insbesondere die Kombinationen aus
/etl/list
/etl/job/list/{component}
und für Masken
/form/{tid}
/report?tid={tid}
relevant.
