REST Webservice API

Der webPDF-Server stellt seine Funktionen als REST-Webservices bereit. Alle REST-Webservices sind über die Basis-URL

 
http://localhost:8080/webPDF/rest

 

erreichbar (ersetzen Sie ggf. "http://localhost:8080" durch die Adresse ihres installierten webPDF-Servers). Zum Aufruf der Funktionen wird das Hypertext Transfer Protokoll (HTTP) verwendet, dessen Aufbau und Funktionsweise als Basis für die Nutzung der REST-Webservices gilt.

 

Die REST-Webservices lassen sich unter der Basis-URL in drei Bereiche aufteilen:

 

1.Authentication - Anmeldung am Server und Erstellung einer Session
/authentication/...
 

2.Dokumente (Storage) - Dokumente in der Session verwalten
/documents/...
 

3.Operationen - Ausführen von Operationen auf den Dokumenten in der Session. Aktuell gibt es sieben Operationen zur Ausführung der PDF-Funktionen des Servers.
/converter/... - Dokumente von Fremdformaten in PDF konvertieren
/signature/... - PDF-Dokumente digital signieren
/pdfa/... - PDF-Dokumente nach PDF/A konvertieren und validieren
/toolbox/... - PDF-Dokumente bearbeiten, wie z.B. "split", "merge" oder "export"
/urlconverter/... - Komplette Websites in PDF-Dokumente konvertieren
/ocr/... - Grafiken oder PDF-Dokumente mit Texterkennung bearbeiten
/barcode/... - Barcodes in PDF-Dokumenten anbringen oder erkennen

 

Zusammenfassend bilden alle Webservices die REST-API des webPDF-Servers.

 

Die technische Dokumentation und Auflistung der REST-API (als OpenAPI) bzw. aller REST-Endpunkte (Ressourcen) finden Sie Online auf unserem Server unter https://portal.webpdf.de/webPDF/help/restful/ oder dem (lokalen) installierten webPDF-Server unter http://localhost:8080/webPDF/help/restful/.

 

Die Endpunkte (Ressourcen) des webPDF-Servers werden bei der REST-API über Uniform Resource Identifier (URI) angesprochen. Die verschieden URI der Webservices können Parameter wie z.B. "{documentId}" enthalten, um ein bestimmtes Dokument anzusprechen und eine Operation auf diesem Dokument auszuführen.

 

Je nach Endpunkt stehen die verschiedenen HTTP-Methoden PUT, GET, POST und DELETE zur Verfügung, um eine Aktion auf dem Endpunkt auszulösen.

 

Beispiel: Aktion (GET) "Auslesen der Dokumenteninformationen" am Endpunkt /documents/{documentId}/info für das Dokument mit der "{documentId} = 26fe0636b6044c2aa0cbfeb1fd5a795e"

 

GET http://localhost:8080/webPDF/rest/documents/26fe0636b6044c2aa0cbfeb1fd5a795e/info
 
{
"documentId": "26fe0636b6044c2aa0cbfeb1fd5a795e",
"parentDocumentId": "",
"fileSize": 12703,
"mimeType": "image/jpg",
"fileName": "sample",
"fileExtension": "jpg",
"fileTypeId": 1535,
"fileTypeGroups": "IMAGE",
"fileLastModified": "Tue, 04 Aug 2020 07:33:34 GMT",
"isFileLocked": false,
"metadata": {},
"error": {
  "errorMessage": "No error",
  "errorCode": 0,
  "stackTrace": ""
}
}

 

 

Antworten und Übergabe von Parametern

 

Der Datenaustausch der REST-Webservices mit der Client-Anwendung, also die Steuerung der Webservices mit Parametern oder die Rückgabe von Informationen (siehe vorheriges GET-Beispiel) als Antwort auf einen REST-Webservice, erfolgt über JSON (JavaScript Object Notation) (http://www.json.org/) Datenstrukturen.

 

In den JSON-Datenstrukturen (Objekten) können mittels der einzelnen Elemente und Parameter mit Werten die Ausführung und das Verhalten der Webservices gesteuert werden oder Informationen abgerufen werden.

 

Aufrufende Clients sollten daher die HTTP-Header "Content-Type" und "Accept" bei den Anfragen auf "application/json" setzen.

 

Content-Type: application/json
Accept: application/json

 

 

hint

Bei POST /documents (Dokumenten-Upload) muss  "Content-Type: multipart/form-data" gesetzt werden.

 

Die entsprechende JSON-Struktur wird im "request body" der HTTP-Methode übergeben (z.B. POST). Liefert ein entsprechender HTTP-Aufruf (z.B. GET) eine Antwort als JSON-Struktur, so ist dies im "response body" der Antwort enthalten.

 

Bsp. einer JSON-Struktur beim Aufruf des Webservice "Converter"

 

POST http://localhost:8080/webPDF/rest/converter/26fe0636b6044c2aa0cbfeb1fd5a795e
 
{
"converter": {
  "pages": "*",
  "accessPassword": "xyz",
  "compression": true,
  "dpi": 300,
  "embedFonts": true,
  "jpegQuality": 90,
  "reduceResolution": true    
 }
}

 

hint

Die Nutzung der REST-API können Sie am besten im Portal von webPDF verfolgen, wenn Sie die Aufrufe mit dem entsprechender Browser-Debugger verfolgen.