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 storage is assigned to the user by a access token (Authorization) and forms a 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 storage using appropriate HTTP operation such as POST or GET.
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" (Zugriffstoken gekürzt)
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 gets a unique ID (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 functions 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. 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})