Using the web services
The easiest way to discover the webPDF server's web services API is to use the REST interface with an HTTP client. With such a client, you can directly send HTTP commands to the server and the REST web services. In this way, you can also see the server's response immediately. This way you can test the API of the web services step by step.
HTTP clients
As HTTP client the following tools are suitable:
Both tools can be executed directly from the command line (via terminal) and are easy to install. In the following description we use curl for the terminal.
Besides the terminal version, HTTPie also has a desktop version and online app version.
Install curl
You can find the latest version of curl for download at https://curl.se/download.html.
curl under Windows
All the modern Windows versions, starting with Windows 10 (version 1803) and Server 2019, have the curl executable pre-installed, so there is no need for a manual installation. To determine the curl location and version in your system, you can use the following commands (at the Windows command prompt):
where curl
curl --version
curl under Linux
For most Linux distributions, the curl executable is available via the package manager of the respective distribution. As an example, here is the installation under Debian via the shell:
$ sudo apt install curl
After the installation you can check the version in the shell:
$ curl --version
If you do not want to install curl locally, then you can also use the official Docker image "curlimages/curl".
Invoking curl
The curl command uses the following syntax:
curl [options...] [url]
It supports various options. As with any other command-line tool, you can use the curl --help command to get help.
To get detailed help, you can use curl --help all. The help section is divided into categories, so the curl --help category gets you an overview of all the categories.
Now that you’ve become familiar with curl syntax, let’s start with the web services usage.
Call the web service API
To test the functionality of the webPDF REST API and understand the flow, you will use some curl requests to make the individual calls to the REST API and see the responses.
Below is the entire flow of a document conversion using webPDF. For this purpose, the corresponding commands are called with curl and the responses are displayed. You can follow the flow by taking the curl requests and using them with your curl and webPDF server installation.
The listing of response headers has been shortened for clarity, so entries like expires, last-modified or date may be missing.
1. Log in and create session
First, we need to request an authorization from the server in the form of a token (Json Web Token (JWT)) to get access to the server and the API. We obtain this authorization by performing authentication at the authentication/user/login endpoint.
curl -X GET -i -H "Accept: application/json" -H "Authorization: Basic YWRtaW46YWRtaW4=" http://localhost:8080/webPDF/rest/authentication/user/login
HTTP/1.1 200
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0
Content-Type: application/json
Content-Length: 773
{
"expiresIn": 3599,
"token": "eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw",
"refreshToken": ""
}
With the Authorization header, the user is logged in via Basic and admin:admin (BASE64 encoded YWRtaW46YWRtaW4=) and a session is created. As a response the token (JWT) eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw (access token shortened) is delivered for the session, which must be specified as Bearer: [TOKEN] in the Authorization header for all further calls.
webPDF can also work with an external authorization that you get from an external OAuth2 provider (e.g. Azure AD). In this case, no login to the above endpoint is necessary. However, the server must be configured accordingly to be able to validate the external authorization.
2. (Optional) Get information about the logged-in user.
curl -X GET -i -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" http://localhost:8080/webPDF/rest/authentication/user/info
HTTP/1.1 200
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0
Content-Type: application/json
Content-Length: 197
{
"userName": "admin",
"roles": [
"admin",
"user"
],
"userLimits": {
"type": "user",
"uploadLimit": 0,
"maxFiles": 0,
"diskSpaceLimit": 0
},
"uniqueId": "dd042dab283143e6a9b689d13136bfe1",
"isUser": true,
"isAdmin": true
}
Information is read for the logged-in user with the session token eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw.
3. Upload document to the server
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
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
The document sample.jpg is loaded onto the server with a POST. The document is sent to the server as Content-Type: multipart/form-data. The file is located in the form-data field filedata (with the reference @sample.jpg to the local file with the name sample.jpg).
The server responds to a successful upload with a 303 - SEE OTHER and refers to the URI of the document in Location. The URI contains the ID 605c045c129a40adb95d7623e279fe8a of the document, which is necessary for further accesses to the document. Either extract the ID from the Location header or follow the 303 - SEE OTHER and retrieve the entire info structure for the document via the URI of the Location header (see the following call).
4. (Optional) Retrieve info structure of the document.
curl -X GET -i -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a/info
HTTP/1.1 200
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0
Content-Type: application/json
Content-Length: 349
{
"documentId": "605c045c129a40adb95d7623e279fe8a",
"parentDocumentId": "",
"fileSize": 11277,
"mimeType": "image/jpeg",
"fileName": "sample",
"fileExtension": "jpg",
"fileTypeId": 1535,
"fileTypeGroups": "IMAGE",
"fileLastModified": "Tue, 04 Aug 2020 12:03:35 GMT",
"isFileLocked": false,
"metadata": {},
"error": {
"errorMessage": "No error",
"errorCode": 0,
"stackTrace": ""
}
}
About the document 605c045c129a40adb95d7623e279fe8a the information is retrieved from the server and returned as JSON structure. From this structure, the information, such as the documentID, about the document can be easily obtained.
5. Convert document to PDF
curl -X POST -i -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" -d '{"converter": {"embedFonts": true,"jpegQuality": 90}}' http://localhost:8080/webPDF/rest/converter/605c045c129a40adb95d7623e279fe8a
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
The converter web service /converter is called for the document 605c045c129a40adb95d7623e279fe8a and controlled with the parameters -d '{"converter": {"embedFonts": true, "jpegQuality": 90}}' (embed fonts and set JPEG images to 90%). The webPDF server converts the document and saves the modified document back to the server as 605c045c129a40adb95d7623e279fe8a.
Optionally, additional operations (e.g. toolbox web service /toolbox) can now be performed on the document.
6. Download document
curl -X GET -i -H "Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" -o sample.pdf http://localhost:8080/webPDF/rest/documents/605c045c129a40adb95d7623e279fe8a
% Total % Received % Xferd Average Speed Time Time Time Current
100 6139 100 6139 0 0 374k 0 --:--:-- --:--:-- --:--:-- 374k
The PDF document 605c045c129a40adb95d7623e279fe8a converted in the previous step is downloaded and saved locally as -o sample.pdf.
7. Log out and end session
curl -X GET -i -H "Accept: application/json" -H "Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw" http://localhost:8080/webPDF/rest/authentication/user/logout
HTTP/1.1 200
Cache-Control: no-cache, no-store, no-transform, proxy-revalidate, max-age=0
Content-Length: 0
Log off the server and end the session with the token eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw. This deletes all documents from the server and logs the user off.