REST API vs Render Links
Explaining differences between generating renders using render links and via the REST API
Renders can be generated with Urlbox in two main ways, directly through render links or through calling endpoints on the REST API.
Here we'll call out some of the differences between the two methods.
Render Links
Render links are a specific URL format that contains your api key, an auth token, an output format followed by a query string of url-encoded options.
https://api.urlbox.io/v1///?
The main advantage of using render links is that you can embed them right inside an <img>
tag on your page or in an email, or anywhere that an image can be rendered.
Render links are also great for:
- Embedding screenshots in emails
- Embedding screenshots in slack messages, tweets, etc.
- Embedding screenshots in your HTML for example, Open Graph tags.
- Quick sharing of a urlbox request with all of the options in one string.
The typical workflow is:
- The render link is generated on the server using the server side language of your choice. We have example code to help with this step in various languages.
- The render link is then embedded in a HTML template (or email template) and sent to the browser.
- When the page gets loaded by a users browser..
- If the render is already cached in our CDN, it will be returned immediately.
- Otherwise, the API will be called and a fresh screenshot or render will be generated.
If you're using a frontend framework such as React, Svelt, Vue or Angular, it's recommended to have a server-side component that generates the render link and passes it back to your frontend, as you don't want to leak your secret key in the browser.
Meta frameworks like Next.js, Remix, Nuxt.js and SvelteKit make adding a server function like this very easy.
Caching of render links
Render links are cached for 30 days. This means that if you generate a render link for a given URL and options, the next time you generate a render link for the same URL and options, it will be returned immediately from our cache.
Once the cache expires, the next time the render link is requested, a fresh render will be generated.
Requests to cached render links do not count against your monthly quota.
Changing the expiry of render links
It's possible to change the duration that we cache the render links for. You can do that by passing in the number of seconds into the ttl
option. (ttl stands for time to live and is a common term in caching).
For example, if you wanted to cache the render link for 1 day, you would pass in a ttl
of 86400
seconds.
Changing the response type
By default the response type of a render link is going to be the binary data of the render itself, so that an img or meta tag can render it. If you prefer to get a JSON response similar to the REST API, you can pass in the response_type
option and set it to json
.
Busting the cache
The cache key is based on the query options combined with the format in the render link. The order of query options doesn't matter for caching purposes.
If you want to get up to date screenshots before the cache expires, one way to bust the cache is to use the unique
parameter by passing in a unique string, such as a timestamp.
Forcing a fresh screenshot
If you want to force a fresh screenshot, you can pass in the force
parameter with a value of true
.
We don't recommend using this option when embedding the URL's directly in your HTML as it will cause the screenshot to be regenerated every time the page is loaded.
Deleting a cached render link
It's possible to remove a cached render link from our cache by sending a DELETE
to the same URL. This will remove it both from our cache and also expire it in cloudflares CDN.
Deduplication of render links
Because the typical use case for render links is to embed them in HTML, if there are two or more requests made for the same combination of options, we will only generate one screenshot and duplicate, in-flight requests will receive a 307 temporary redirect, which will end up receiving the same response as the original request.
Always Synchronous
Render links are always synchronous. You can still use a webhook_url
in a render link, but it makes more sense to use them with the asynchronous API.
You can also call the render link with HEAD
rather than GET
if you just want to generate the render but not download it.
Error handling
Error responses will always be returned in JSON format. When using render links embedded in an image tag, it's more difficult to handle errors as the browser will just display a broken image. If you want to make it easier to handle errors, it's better to use the REST API or call the render link directly using a GET
or HEAD
request.
Accessing response headers
It's also not easy to access response headers if the render link is embedded in an image tag. If you want to access response headers, it's better to use the REST API or explicitly call the render link with HEAD
or GET
.
URL length
Because of various limits on URL length, render links are not a great option for rendering from HTML, or when passing options with large payloads, such as custom javascript or css. For these types of requests it's better to use the REST API.
API
The API is made up of various endpoints that accept a JSON (or form encoded) payload of options that are POST
ed to them and returns a JSON response with the URL to the render.
The API is again intended to be used on the server side, as it uses your projects secret key for authentication in the Authorization
response header.
One advantage of using the API is that you can pass in larger payloads of options, such as custom javascript, or HTML to render.
Asynchronous or synchronous
Depending on the endpoint you call, the API can be used either synchronously (/v1/render/sync
) or asynchronously (/v1/render/async
). The synchronous endpoint will return the render in the response, whereas the asynchronous endpoint will return a status URL which can be polled.
Webhooks can also be triggered by passing in a webhook_url
option.
Caching of API requests
API requests are not cached, so every request will generate a fresh render.
Deduplication of API requests
Requests through the API endpoints are not deduplicated, so if you make two requests for the same URL with the same options, two renders will be generated.
Response format
The default response is JSON, but you can also request a binary response by passing in the response_type
option and setting it to binary
.
Response headers
Several useful response headers are returned when calling either sync or async endpoints.