Server-Modus (REST API) PRO

Der Publisher bietet eine Schnittstelle an, mit der über HTTP Aufträge zur Dokumentenerzeugung übergeben werden können. Gestartet wird der Servermodus mit

sp server

auf der Kommandozeile. Der Servermodus bietet die Möglichkeit

• Daten zum Server zu übertragen und einen Lauf zu starten
• Status des Laufs zu ermitteln (läuft der Prozess noch?)
• fertige PDF-Dateien herunterzuladen
• Protokoll- und andere Dateien aus dem Arbeitsverzeichnis abzurufen

Der Server baut die Verbindung auf der IP-Adresse 127.0.0.1 und dem Port 5266 auf. Die Adresse kann mit den Parametern address und port in der Konfigurationsdatei bzw. auf der Kommandozeile geändert werden, siehe den Anhang über die Konfiguration.

Beispiel für eine Konfigurationsdatei:

[server]
port = 9999
address = 0.0.0.0
extra-dir = /var/projects/fonts:/var/projects/images
filter = convertdata.lua

Es folgt ein Überblick über alle API Methoden. Die aktuelle Versionsnummer der API ist 1, also werden alle Methoden über http://127.0.0.1:5266/v1/.. angesprochen.

Fehlerformat

Alle Fehlerantworten der v1-API verwenden das Format nach RFC 9457 (Problem Details for HTTP APIs) mit dem Content-Type application/problem+json:

{
  "type": "about:blank",
  "title": "Job not found",
  "status": 404,
  "detail": "No job with id \"123\" exists",
  "instance": "/v1/jobs/123"
}

/v1/available

GET: Gibt den HTTP-Status 200 mit einer JSON-Antwort zurück:

{"status": "ok"}

POST /v1/jobs

Startet einen neuen Publishing-Lauf. Der Request-Body kann optional eine JSON-Datei im folgenden Format enthalten:

{
  "<dateiname>": "<base64 kodierter Inhalt>",
  "<dateiname>": "<base64 kodierter Inhalt>"
}

also z. B.

{
  "layout.xml": "PD94bWwgdmVyc2lv....",
  "data.xml": "PGRhdGE+CiAgICA8Y29udGVudHM+PCFbQ0RBVEFbPHV..."
}

Der Body kann auch leer sein, wenn keine Dateien übertragen werden sollen (z. B. wenn Layout und Daten über extra-dir bereitgestellt werden).

Diese Dateien werden auf dem Server in ein leeres Verzeichnis kopiert und dort wird sp aufgerufen. Die Rückgabe ist in der Form

{"id": "752869708"}

mit einem HTTP-Statuscode 201 (Created).

Parameter

Folgende URL-Parameter können beim POST-Request angegeben werden:

vars

Setzt Variablen für den Publisher-Lauf. Angabe in der Form var1=wert1,var2=wert2,var3=wert3..., jedoch URL-kodiert.

mode

Setzt den Modus für den Lauf. Angabe in der Form mode1,mode2,mode3..., aber URL-kodiert.

Beispiel

curl -X POST "http://127.0.0.1:5266/v1/jobs?vars=myvar%3D12345&mode=a4paper%2Cprint"

setzt myvar auf 12345 und schaltet die Modi a4paper und print ein. Die Antwort enthält die Job-ID:

{"id": "752869708"}

GET /v1/jobs

Liefert den Status aller Publishing-Läufe zurück.

{
  "jobs": [
    {
      "id": "1997009134",
      "status": "finished",
      "message": "no errors found",
      "finished": "2016-05-23T11:14:14+02:00"
    },
    {
      "id": "1997329145",
      "status": "processing"
    }
  ]
}

Mögliche Werte für status: finished, failed, processing, error.

GET /v1/jobs/{id}

Ermittelt den Status eines einzelnen Publishing-Laufs.

Falls der Lauf noch nicht abgeschlossen ist, wird HTTP-Statuscode 202 (Accepted) zurückgegeben:

{
  "id": "752869708",
  "status": "processing"
}

Falls der Lauf abgeschlossen ist, wird HTTP-Statuscode 200 (OK) zurückgegeben:

{
  "id": "752869708",
  "status": "finished",
  "message": "no errors found",
  "finished": "2015-12-25T12:03:04+01:00"
}

Falls die ID unbekannt ist, wird HTTP-Statuscode 404 mit einer RFC 9457 Fehlerantwort zurückgegeben.

GET /v1/jobs/{id}/pdf

Gibt die erzeugte PDF-Datei zurück. Der Request wartet auf die Fertigstellung des Publishing-Prozesses.

Parameter

jobname

Setzt den Dateinamen der PDF-Ausgabe im HTTP-Header Content-Disposition. Ohne Angabe wird publisher.pdf verwendet.

keep

Auf true setzen, um das Arbeitsverzeichnis nach dem Download zu behalten. Ohne Angabe wird das Verzeichnis nach dem PDF-Abruf automatisch gelöscht.

Beispiel

curl "http://127.0.0.1:5266/v1/jobs/752869708/pdf?jobname=Vertrag2026" -o vertrag.pdf

Rückgabewerte

200 OK

PDF wurde fehlerfrei generiert. Die Datei wird mit Content-Type: application/pdf und einem Content-Disposition Header zurückgegeben. Das Arbeitsverzeichnis wird anschließend gelöscht, sofern nicht keep=true angegeben wurde.

404 Not Found

ID ungültig.

406 Not Acceptable

PDF wurde mit Fehlern generiert.

POST /v1/pdf

Sendet Daten an den Server und erhält das PDF in demselben Request zurück. Die Kodierung der Daten entspricht der von POST /v1/jobs, die Rückgabewerte entsprechen denen von GET /v1/jobs/{id}/pdf.

GET /v1/jobs/{id}/files/{filename}

Liefert eine beliebige Datei aus dem Arbeitsverzeichnis eines Publishing-Laufs. Nützlich z. B. für die Protokolldatei:

curl "http://127.0.0.1:5266/v1/jobs/752869708/files/publisher-protocol.xml"

200 OK

Die Datei wird mit einem automatisch erkannten Content-Type zurückgegeben.

404 Not Found

ID oder Dateiname ungültig.

DELETE /v1/jobs/{id}

Löscht das Arbeitsverzeichnis eines Publishing-Laufs.

204 No Content

Erfolgreich gelöscht.

404 Not Found

ID ungültig.

Beispiel

curl -X DELETE "http://127.0.0.1:5266/v1/jobs/752869708"

Komplettes Beispiel

Ein typischer Workflow mit der v1-API:

# 1. Job starten
ID=$(curl -s -X POST "http://127.0.0.1:5266/v1/jobs?vars=mode%3DVERTRAG" | jq -r '.id')
echo "Job gestartet mit ID: $ID"

# 2. Status prüfen (HTTP 202 = läuft noch, 200 = fertig)
curl -s "http://127.0.0.1:5266/v1/jobs/$ID"

# 3. PDF herunterladen (wartet auf Fertigstellung)
#    Das Arbeitsverzeichnis wird danach automatisch gelöscht.
curl -s "http://127.0.0.1:5266/v1/jobs/$ID/pdf?jobname=Vertrag" -o Vertrag.pdf

Falls zusätzlich die Protokolldatei benötigt wird, muss das Arbeitsverzeichnis mit keep=true erhalten bleiben:

# 3a. PDF herunterladen, Arbeitsverzeichnis behalten
curl -s "http://127.0.0.1:5266/v1/jobs/$ID/pdf?jobname=Vertrag&keep=true" -o Vertrag.pdf

# 4. Protokolldatei abrufen
curl -s "http://127.0.0.1:5266/v1/jobs/$ID/files/publisher-protocol.xml" -o protokoll.xml

# 5. Arbeitsverzeichnis manuell löschen
curl -s -X DELETE "http://127.0.0.1:5266/v1/jobs/$ID"