pdfToolbox in the cloud- How to
To get to know the API, you can use the HTML based demo client.
- For simplicity the examples are presenteded using cURL, but ...
- The API itself is not restricted to a specific client language or library as long as regular ReST methods are supported using GET and POST HTTP requests
- To get to know the API, you can also use the HTML based demo client. However this client is not intended to be used for production purposes. A typical use case for the API is e.g. in a customers own backend service
URL format
URLs are composed of …
the scheme part (https)
the server part (api.callassoftware.io)
the path part (depends on the resource to be used)
examples …
https://api.callassoftware.io/v1/pdfToolbox
https://api.callassoftware.io/v1/pdfToolbox/saveasimg
https://api.callassoftware.io/v1/result/5a56290d-8422-4bfb-a95f-792656ddefc4
Many responses bodies contain a path component that is to be used in subsequent requests. It depends on the used framework (or client) library whether this path can be used as-is, or if it is necessary to prepend it with the scheme and/or the server part.
HTTP Messages
All data is exchanged using the JavaScript Object Notation (aka JSON).
Request Body example
Only POST requests have a message body.
{
"finput": "https://s3.eu-central-1.amazonaws.com/ccapi-sample/sample.pdf",
"imgformat": "PNG"
}
Response Body example
{
"message": "operation enqueued for asynchronous processing (keep going using a GET on the belonging path ...)",
"ms_retry_after": 200,
"operation": "saveasimg",
"path": "https://node5.brb234ay220.de/v1/result/4a56290d-8422-4bfb-a95f-792656ddefc4",
"progress": 0,
"state": "INITIAL"
}
HTTP Status Codes
Status Code |
Meaning |
Comment |
---|---|---|
202 | Accepted |
Operation is pending |
4xx |
Client Error | Error caused by client. The user should examine the error cause and try to fix it |
200 | OK | Operation completed successfully |
5xx | Server Error | Internal server error. Not fixable by the user |
Get a list of operations
A list of available operations is received by submitting a GET request.
Request
curl -X GET https://api.callassoftware.io/v1/pdfToolbox
Response
{
"message": "available operations",
"externalDocs": {
"description" : "Available Operations",
"url" : "https://www.callassoftware.com/en/pdftoolboxinthecloud-howto"
},
"operations": [
{
"name": "preflight",
"description": "preflight an input file and save results with or without reports",
"path": "https://api.callassoftware.io/v1/pdfToolbox/preflight"
},
{
"name": "preflight_vars",
"description": "retrieve variable keys from a pdfToolbox profile",
"externalDocs": {
"description": "Enumprofiles Details",
"url": " https://www.callassoftware.com/goto/tbx_ENG_cloud_enumprofiles"
},
"path": "https://api.callassoftware.io/v1/pdfToolbox/preflight_vars"
},
{
"name": "saveasimg",
"description": "save an input file as images (one per page)",
"externalDocs": {
"description": "SaveAsImage Details",
"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_saveasimg"
},
"path": "https://api.callassoftware.io/v1/pdfToolbox/saveasimg"
},
{
"name": "splitlayers",
"description": "split layers into single PDFs (one per layer)",
"externalDocs": {
"description": "Split Layers Details",
"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_splitlayers"
},
"path": "https://api.callassoftware.io/v1/pdfToolbox/splitlayers"
},
{
"name": "dieline",
"description": "extract dieline(s) from PDF",
"externalDocs": {
"description": "Extract Dieline Details",
"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_dieline"
},
"path": "https://api.callassoftware.io/v1/pdfToolbox/dieline"
},
{
"name": "splitatmark",
"description": "split PDF at mark",
"externalDocs": {
"description": "splitatmark Details",
"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_splitatmark"
},
"path": "https://api.callassoftware.io/v1/pdfToolbox/splitatmark"
}
]
}
Get a list of operation parameters
Each operation has at least one mandatory and possibly some optional parameters. A description of these parameters is received by submitting a GET request to the operation path.
curl https://api.callassoftware.io/v1/pdfToolbox/saveasimg
Post an operation and fetch the result
For a POST request, an x-api-key header field needs to be provided that can be obtained from callas software. The typical "workflow" for e.g. a saveasimg
operation is like below (in a pseudocode "language")
response = POST https://api.callassoftware.io/v1/pdfToolbox/saveasimg
while (${response.statuscode} == 202):
if (${response.body} contains ms_retry_after): delay ${response.body.ms_retry_after}
response = GET https://api.callassoftware.io/${response.body.path}
if (${response.statuscode} == 200):
GET ${response.body.result_url}
else:
console.log an error occured. See ${response.body.message}
Further details on POSTing a request.