REST Web Service API
The webPDF server provides its functions as REST web services. All REST web services are accessible via the base URL
http://localhost:8080/webPDF/rest
(replace "http://localhost:8080" with the address of your installed webPDF server if necessary). The Hypertext Transfer Protocol (HTTP) is used to call the functions, the structure and functionality of which is considered the basis for the use of REST web services.
The REST web services can be divided into three groups under the base URL:
Authentication
Login to the server and create a session: /authentication/...
Dokumente (Storage)
Manage documents in the session: /documents/...
Operations
Perform operations on the documents in the session.
Currently there are seven operations for executing the server's PDF functions.
/converter/... - Convert documents from foreign formats to PDF (API {REST})
/signature/... - Digitally sign PDF documents (API {REST})
/pdfa/... - Convert and validate PDF documents to PDF/A (API {REST})
/toolbox/... - Edit PDF documents, with operation such as "split", "merge" or "export" (API {REST})
/urlconverter/... - Convert complete websites to PDF documents (API {REST})
/ocr/... - Edit graphics or PDF documents with text recognition (API {REST})
/barcode/... - Apply or recognize barcodes in PDF documents (API {REST})
In summary, all web services form the REST API of the webPDF server.
The technical documentation and listing of the REST API as OpenAPI can be found online on our server at https://portal.webpdf.de/webPDF/help/restful/ or the (local) installed webPDF server at http://localhost:8080/webPDF/help/restful/.
The endpoints (resources) of the webPDF server are addressed via Uniform Resource Identifier (URI) in the REST API. The various URIs of the web services can contain parameters such as {documentId} to address a specific document and perform an operation on that document.
Depending on the endpoint, the different HTTP methods PUT, GET, POST and DELETE are available to trigger an action on the endpoint.
Example: Action (GET) "Read the document information" at the /documents/{documentId}/info endpoint for the document with the {documentId} = 26fe0636b6044c2aa0cbfeb1fd5a795e.
GET http://localhost:8080/webPDF/rest/documents/26fe0636b6044c2aa0cbfeb1fd5a795e/info
The endpoint responds with a JSON structure, which can look like this, for example:
{
"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": ""
}
}
Responses and passing parameters
The data exchange of the REST web services with the client application, i.e. the control of the web services with parameters or the return of information (see previous GET example) in response to a REST web service, is done via JSON (JavaScript Object Notation) (http://www.json.org/) data structures.
In the JSON data structures (objects), the execution and behavior of the web services can be controlled or information can be retrieved by means of the individual elements and parameters with values.
Calling clients should therefore set the HTTP headers "Content-Type" and "Accept" to "application/json" in the requests.
Content-Type: application/json
Accept: application/json
For POST /documents (document upload) "Content-Type: multipart/form-data" must be set.
The corresponding JSON structure is passed in the "request body" as the “payload” of the HTTP method (e.g. POST). If a corresponding HTTP method (e.g. GET) returns a response as a JSON structure, this is included in the response body.
Example of calling the converter web service with POST and...
POST http://localhost:8080/webPDF/rest/converter/26fe0636b6044c2aa0cbfeb1fd5a795e
...the corresponding parameters in the payload.
{
"converter": {
"pages": "*",
"accessPassword": "xyz",
"compression": true,
"dpi": 300,
"embedFonts": true,
"jpegQuality": 90,
"reduceResolution": true
}
}
The best way to track the usage of the REST API is in the webPDF portal, using the appropriate browser debugger to track the calls.
All operations and related parameters are described in the REST API.