pdfToolbox in the cloud- Server Sent Events

Most ReST API clients use a polling approach to retrieve the processing results from the callas ReST API.

response = POST https://api.callassoftware.io/v1/pdfToolbox/saveasimg
while (response.statuscode == 202):
    delay (response.body.ms_retry_after)
    response = GET response.body.path
if (response.statuscode == 200):
    console.log done. see result files from response.body.result_url
    console.log an error occured. See response.body.message

This approach is very easy to understand and use. It works quite well for processing requests that do not take very long, e.g. only a few seconds.

However, for processing requests that take significantly longer, the high number of needed GET requests can be problematic, for example it is possible that an apigateway responds with an error of HTTP/429 Too many Requests when the amount of GET requests exceeds a certain limit within a duration interval. There are several different non-polling approaches that can be used to avoid such a situation, such as:

  • HTTP Web Hooks (easy enough to use but not working behind NAT/VPN/Firewalls)
  • Web Sockets (not working behind NAT/VPN/Firewalls, requires a permanent connection, difficult to use)
  • HTTP/1xx informational responses (easy enough to use, but many client framework struggle to handle this correctly)
  • Server Sent Events (well defined, even working behind NAT/VPN/Firewalls, easy to use)

Among these non-polling approaches only Server Sent Events are supported by the callas cloud api.

How to use Server Sent Events

Server Sent Events are enabled by sending an HTTP Header in the initial POST request:

x-ccapi-enable-sse: true

As always, the API responds with a regular HTTP/202 Response. But in addition, this Response Header contains a header field containing the URL of an SSE proxy that can be used to receive events without the need for polling:

x-ccapi-sse-proxy: https://proxy-host.de:443/v1/monitor/b396-6eb2b01859

From now on, it is possible to receive SSE events by opening an SSE EventSource on the received proxy ressource. For example in javascript this can be used via:

let evs = new EventSource(https://proxy-host.de:443/v1/monitor/b396-6eb2b01859);
evs.onmessage = async function (msg) {
let jdata = JSON.parse(msg.data);
console.log(`jdata.state jdata.progress %`);

The event source is automatically closed as soon as a value of COMPLETED is received in the state field. Afterwards a regular GET request can be used to retrieve the final result.