Bei der REST-Schnittstelle findet die Kommunikation zwischen der Client-Anwendung und jadice server
über normale HTTP-Aufrufe und die Methoden GET,
POST und DELETE statt. Die Nachrichten werden
dabei im XML- oder JSON-Format ausgetauscht.
Um die REST-Schnittstelle nutzen zu können, muss sie zunächst wie im Abschnitt „Konfiguration REST-Schnittstelle“ beschrieben aktiviert werden und ist unter
http://
erreichbar. Zur besseren Lesbarkeit wird der Hostname der URL
(<hostname>:9001/jadiceServer/http://) in den nachfolgenden
Abschnitten weggelassen.
<hostname>:9001
Die folgenden Abschnitte geben eine kurze Übersicht über die zur Verfügung stehenden Methoden. Im Abschnitt „Ablauf der Verarbeitung über REST“ wird gezeigt, wie daraus der Ablauf einer Konvertierung zusammengesetzt wird.
Die REST-Schnittstelle verfügt über eine integrierte Dokumentation im
Open API-Format (auch
bekannt als „swagger“. Unter der URL /jadiceServer/swagger.json
kann sie im JSON-Format bzw. unter /jadiceServer/swagger.yaml
im YAML-Format abgerufen werden.
Unter der URL /jadiceServer/api-docs?url=/jadiceServer/swagger.json finden
Sie eine interaktive Dokumentation der REST-Schnittstelle. Dort können
Sie direkt aus dem Browser heraus die verfügbaren Methoden aufrufen:
Um Dateien hochzuladen, damit jadice server sie anschließend verarbeiten kann, oder um Ergebnisdateien von
jadice server abzurufen, ist der File-Service zuständig. Dieser ist
unter der URL /jadiceServer/files erreichbar.
Folgende Methoden sind damit möglich:
POSTauf/jadiceServer/files- Hochladen einer neuen Datei. Der Rückgabewert ist die ID, unter der diese
Datei in den nachfolgenden Schritten abrufbar ist (im Folgenden
{fileId} GETauf/jadiceServer/files/{fileId}- Lädt eine Datei herunter. Ihr Dateiname und MIME-Type werden in die üblichen
Header-Felder
Content-DispositionundContent-Typeübertragen. DELETEauf/jadiceServer/files/{fileId}- Löscht eine Datei vom Server.
Über den Template-Service kann erfragt werden, welche
Job-Templates zur Verfügung stehen. Sie folgen der im Abschnitt „Definition von Job-Templates“ dargestellten Syntax und liegen
i. d. R. im Unterordner /server-config/jobtemplates.
Folgende Methoden stellt der Template-Service zur Verfügung:
GETauf/templates- Lädt die Liste aller verfügbaren Job-Templates herunter. Die Liste stellt
die IDs dar, unter denen die einzelnen Job-Templates referenziert werden können
(im Folgenden
{templateId} GETauf/templates/{templateId}- Lädt ein bestimmtes Job-Template herunter. Da diese im XML-Format definiert werden, ist hier keine Rückgabe im JSON-Format möglich.
Der Job-Service wird dafür genutzt, um Konvertierungsanfragen
an jadice server abzusenden und um sich über deren Fortschritt zu informieren. Ferner bündelt er
die Informationen über die Ergebnis-Dokumente und Log-Meldungen, die während der
Verarbeitung erzeugt werden.
Der Jobs-Service stellt folgende Methoden zur Verfügung:
POSTauf/jadiceServer/jobs- Erstellen eines neuen
Jobs, dessen Verarbeitung sofort angestoßen wird. Der Rückgabewert ist die ID, unter der dieser Job nachverfolgt werden kann (im Folgenden{jobID} GETauf/jadiceServer/jobs/{jobId}- Ruft den aktuellen Job-Zustand ab.
DELETEauf/jadiceServer/jobs/{jobId}- Entfernt die Informationen zu diesem Job vom Server. Falls dieser sich noch in der Verarbeitung befindet, wird er automatisch abgebrochen.
Nachdem im vorherigen Abschnitt die einzelnen REST-Services kurz vorgestellt wurden, soll hier nun examplarisch der Ablauf einer Konvertierung dargestellt werden. Abbildung 7.5, „Sequenzdiagramm der Verarbeitung über REST“ zeigt diesen Ablauf in der Übersicht als UML-Sequenzdiagramm.
In den folgenden Schritten folgt eine textuelle Beschreibung, sowie je ein exemplarischer Request der Clientanwendung und die zugehörige Antwort von jadice server. In den Beispielen wird die Kommunikation im JSON-Format bevorzugt.
Anmerkung
- In den Beispielen werden die HTTP-Header-Felder, die nicht zum Verständnis beitragen, weggelassen.
- Der HTTP-Header und der Body werden durch eine Leerzeile getrennt dargestellt.
- Zur besseren Lesbarkeit werden Umbrüche und Einrückungen in die JSON-Objekte eingefügt.
-
Bevor ein Job an jadice server abgeschickt werden kann, muss zunächst ausgewählt werden, welches Job-Template verwendet werden soll. Um in Erfahrung zu bringen, welche Job-Templates zur Verfügung stehen, wird der Template-Service mit dem
GET-Request auf/jadiceServer/templates/ausgerufen. Das Ergebnis ist die Liste aller zur Verfügung stehenden Templates (bzw. deren IDs) im JSON- oder XML-Format. Wenn Sie auch den Inhalt des Templates kennen möchten, so kann das über denGET-Request auf/jadiceServer/templates/heruntergeladen werden.{templateId}Beispiel 7.13. Abfrage der verfügbaren Job-Templates
Request Response GET /jadiceServer/templates HTTP/1.1 Host: <hostname>:9001 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json { "templates": [ "mail2pdf.xml", "one-node.xml", "x2pdf.xml" ] }Beispiel 7.14. Abfrage eines einzelnen Job-Templates
Request Response GET /jadiceServer/templates/x2pdf.xml HTTP/1.1 Host: <hostname>:9001 Accept: application/xml
HTTP/1.1 200 OK Content-Type: application/xml <job (...) > (...) </job>
-
Die zu verarbeitenden Dateien werden auf den Server hochgeladen: Für jede Datei, die konvertiert werden soll, erfolgt ein Upload in Form eines
POST-Request mit dem Content-Typemultipart/form-dataauf/jadiceServer/files. Als Ergebnis gibt der Server die File-Id zurück, unter der diese Datei anschließend referenziert werden kann.Beispiel 7.15. Hochladen einer Datei
Request Response POST /jadiceServer/files HTTP/1.1 Host: <hostname>:9001 Accept: text/plain Content-Type: multipart/form-data; boundary=----Boundary-12345 ------Boundary-12345 Content-Disposition: form-data; name="file"; filename="my-file.txt" Content-Type: text/plain Lorem Ipsum... ------Boundary-12345--
HTTP/1.1 201 Created Content-Type: text/plain stream-uuid-0001
-
Anschließend kann mit diesen Angaben ein Job formuliert werden, der an den JobService in Form eines
POST-Requests auf/jadiceServer/jobsgeschickt wird. Der Service gibt die Job-Id zurück, unter der dieser Job nachverfolgt werden kann.Beispiel 7.16. Starten eines Jobs
Request Response POST /jadiceServer/jobs HTTP/1.1 Host: <hostname>:9001 Accept: text/plain Content-Type: application/json { "templateId": "x2pdf.xml", "templateParameters": {}, "inputFiles": [ { "fileId": "stream-uuid-0001" } ] }HTTP/1.1 201 Created Content-Type: text/plain job-uuid-0001
-
Der aktuelle Zustand des Jobs wird über den
GET-Request auf/jadiceServer/jobs/ermittelt. Es muss gewartet werden, bis dieser im Zustand{jobId}FINISHEDist. Falls der Job nicht erfolgreich verarbeitet werden kann, endet er im ZustandFAILED, sieheJob.State.Beispiel 7.17. Aktuellen Status des Jobs abfragen
Request Response GET /jadiceServer/jobs/job-uuid-0001 HTTP/1.1 Host: <hostname>:9001 Accept: application/json
HTTP/1.1 200 OK Content-Type: application/json { "templateId":"x2pdf.xml", "templateParameters":{}, "id":"job-uuid-0001", "state":"FINISHED", "inputFiles":[ { "fileId":"stream-uuid-0001", "nodeId":null } ], "resultFiles":[ { "fileId":"stream-uuid-0002", "nodeId":"node2" } ] }
-
Die erzeugten Dateien, deren File-Ids in der Antwort des Job-Service genannt werden, können einzeln über je einen
GET-Request auf/jadiceServer/files/heruntergeladen werden.{fileId}Beispiel 7.18. Herunterladen einer Datei
Request Response GET /jadiceServer/files/stream-uuid-0002 HTTP/1.1 Host: <hostname>:9001 Accept: application/octet-stream
HTTP/1.1 200 OK Content-Type: application/pdf Content-Disposition: attachment; filename=my-file.pdf Content-Description: my-file.pdf %PDF-1.4...
-
Abschließend müssen alle Resourcen, die nicht mehr für eine weitere Konvertierung benötigt werden, gelöscht werden:
-
Die hochgeladenen und die erzeugten Dateien werden jeweils per
DELETE-Request auf/jadiceServer/files/gelöscht.{fileId}Beispiel 7.19. Löschen einer Datei
Request Response DELETE /jadiceServer/files/stream-uuid-0001 HTTP/1.1 Host: <hostname>:9001 Accept: application/json
HTTP/1.1 204 No Content
-
Der Job wird per
DELETE-Request auf/jadiceServer/jobs/gelöscht.{jobId}Beispiel 7.20. Löschen des Jobs
Request Response DELETE /jadiceServer/jobs/job-uuid-0001 HTTP/1.1 Host: <hostname>:9001 Accept: application/json
HTTP/1.1 204 No Content
Wichtig
Das Löschen von nicht mehr benötigten Dateien und Jobs ist essenziell. Diese Ressourcen werden nicht automatisch von jadice server gelöscht und belegen u. U. unnötigen Platz auf der Festplatte und im Arbeitsspeicher.
-
Mit Hilfe der Open API-Spezifikation der REST-Schnittstelle und dem
Kommandozeilenwerkzeug swagger-codegen ist es möglich, eine Client-Bibliothek zu generieren,
die in der gewünschten Implementierungssprache genutzt werden kann. Laden Sie dazu zunächst
die Bibliothek swagger-codegen-cli-
von http://swagger.io/swagger-codegen/ herunter.
<version>.jar
Für welche Sprachen swagger-codegen Client-Bibliotheken erzeugen kann, verrät der Aufruf
von java -jar swagger-codegen-cli-<version>.jar:
Available languages: [android, aspnet5, async-scala, cwiki, csharp, cpprest, dart, flash, python-flask, go, groovy, java, jaxrs, jaxrs-cxf, jaxrs-resteasy, jaxrs-spec, inflector, javascript, javascript-closure-angular, jmeter, nancyfx, nodejs-server, objc, perl, php, python, qt5cpp, ruby, scala, scalatra, silex-PHP, sinatra, rails5, slim, spring, dynamic-html, html, html2, swagger, swagger-yaml, swift, tizen, typescript-angular2, typescript-angular, typescript-node, typescript-fetch, akka-scala, CsharpDotNet2, clojure, haskell, lumen, go-server]
Ein einfacher Java-Client wird mit diesem Kommandozeilenaufruf erzeugt:
java -jar swagger-codegen-cli-<version>.jar generate
--lang java
--input-spec http://<hostname>:9001/jadiceServer/swagger.jsonswagger-codegen bietet diverse Optionen, um die generierte Client-Bibliothek anzupassen. Im folgenden Beispiel werden der Ausgabeordner und die Namespaces angepasst:
java -jar swagger-codegen-cli-2.2.1.jar generate
--lang java
--input-spec http://<hostname>:9001/jadiceServer/swagger.json
--output generated-client
--invoker-package com.acme.invoker --model-package com.acme.model --api-package com.acme.apiAbbildung 7.6, „Von swagger-codegen erzeugtes Java-Projekt“ zeigt die Klassen, die als Ergebnis generiert werden.
