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.