Skip to main content
Version: 10.0

Documents

With REST web services, the webPDF server uses a Document Storage (storage) on the server to store the documents to be processed between web service calls.

This document storage is assigned to the user through authorization and the creation of an access token and is part of the session.

The access token, and thus also the session, is initialized via the "Authentication" web service. If a session is terminated (logout) or expires (timeout), the token becomes invalid, the storage is removed and all documents in it are deleted on the server.

Each time the storage is accessed, the access token must be specified in the request to the REST API (see Authorization). This indirectly references the session and thus the documents in the storage.

To use the storage, the webPDF server provides a web service with the following URI.

/documents/... ( API {REST} )

Documents can be uploaded to or downloaded from the store using appropriate HTTP methods (e.g. GET).

caution

Please note that for each web service call, the access token obtained by "Authentication" must be passed in the HTTP header (or optionally as a query parameter of the same name) (see Authorization).

Example: retrieving information about the document 605c045c129a40adb95d7623e279fe8a from the session with the access token eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw (access token shortened)

curl -X GET -i -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info

Document id​

Each document stored in the storage receives a unique ID, the unique documentId. This ID is created when a document is uploaded and is included in the JSON response of the web service.

curl -X POST -i -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@sample.jpg' http://localhost:8080/webPDF/rest/documents

This ID is then required in the URI of the web services for executing PDF operations to select the document.

Upload a document​

The upload of a document to the storage is done via the following URI as POST in form of a multipart/form-data document.

POST /documents ( API {REST} )

curl -X POST -i -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@Akquise.docx' http://localhost:8080/webPDF/rest/documents  
  
HTTP/1.1 100

In the "request body" the file is passed.

caution

It is important to use the name filedata in Content-Disposition:

-----------------------------202131351012485  
Content-Disposition: form-data; name="name"  
Akquise.docx  
-----------------------------202131351012485  
Content-Disposition: form-data; name="filedata"; filename="Akquise.docx"  
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document  
<... binary data follows ...>

After the upload, the web service responds with an HTTP 303 - SEE OTHER and a URL in the Location header.

HTTP/1.1 303  
Location: http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info  
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0  
Content-Length: 0

Under the URL in Location the further information about the document can now be retrieved. Important in the URL is the documentID 605c045c129a40adb95d7623e279fe8a under which the document is stored on the server.

If now the information is retrieved with the following call, then the server responds with a JSON structure that contains all the information about the document.

curl -X GET -i -H 'Accept: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info
{
  "documentId": "605c045c129a40adb95d7623e279fe8a",
  "parentDocumentId": "",
  "fileSize": 12703,
  "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "fileName": "Akquise",
  "fileExtension": "docx",
  "fileTypeId": 1384,
  "fileTypeGroups": "OFFICE,WORD",
  "fileLastModified": "Mon, 19 Aug 2019 11:01:30 GMT",
  "isFileLocked": false,
  "error": {
    "errorMessage": "No error",
    "errorCode": 0,
    "stackTrace": ""
  }
}

Important in this response is the documentId. This is needed for the further calls to reference the file.

Upload with automatic redirect​

If you use the REST API with a client that can perform an automatic "redirect", then this will shorten the number of calls and you will receive directly as a response the corresponding JSON structure to the uploaded document:

curl -i -L -H 'Content-Type: multipart/form-data' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -F 'filedata=@sample.jpg' http://localhost:8080/webPDF/rest/documents  
  
HTTP/1.1 100  
  
HTTP/1.1 303  
Location: http://192.168.1.31:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info  
...  
  
HTTP/1.1 200  
Content-Type: application/json  
...  
{"documentId":"605c045c129a40adb95d7623e279fe8a","parentDocumentId":"","fileSize":11277,"mimeType":"image/jpeg","fileName":"sample","fileExtension":"jpg","fileTypeId":1535,"fileTypeGroups":"IMAGE","fileLastModified":"Tue, 11 Aug 2020 09:37:44 GMT","isFileLocked":false,"metadata":{},"error":{"errorMessage":"No error","errorCode":0,"stackTrace":""}}

Convert and manage document​

To convert this document, the Converter web service is called with the documentId in the URI:

POST /webPDF/rest/converter/67b4e25d3c1a498e9b5a7f8221b2bf0c ( API {REST} )

To get information about the document in the storage, the following is called:

GET /webPDF/rest/documents/67b4e25d3c1a498e9b5a7f8221b2bf0c/info ( API {REST} )

To then delete this document from the storage, the following is called:

DELETE /webPDF/rest/documents/67b4e25d3c1a498e9b5a7f8221b2bf0c ( API {REST} )