Sync vs Async
Sync vs Async
The Urlbox API can be called in both synchronous and asynchronous modes.
Depending on your use case and desired workflow, you may want to choose one method of calling the API over another.
With render links the request will always be synchronous.
Synchronous requests
Synchronous means that when calling the API the request will wait for the render to finish generating before returning a response.
The render will be returned in this response either as binary data or as a URL to the rendered image depending on how you're calling the API.
When to use synchronous requests
Synchronous requests are useful when you want to get the results back immediately.
When you want to call the Urlbox API directly from an <img>
tag, you can use a render link which will always be synchronous and return the binary data by default.
It is usually easier to use synchronous requests when integrating with no-code solutions such as Zapier.
If your server environment can deal with potentially having many long running connections open at the same time, then synchronous requests might be a good choice.
Asynchronous requests
Asynchronous means that the request will return immediately with a renderId
and statusUrl
(if the request passes validation).
The renderId
can be stored and used to retrieve the render at a later time, either by polling the statusUrl
or by passing in a webhook_url
to be notified when the render is complete.
When to use asynchronous requests
Asynchronous requests are useful when you want to render a large number of URLs or when the render time is long (such as when rendering a very tall page with full_page
set to true).
You can fire off the requests, and either poll the status URL's, or wait for your webhook endpoint to be called.