Working with long running requests

To avoid complexity, the first request for a new preview blocks for a number of seconds until the capture has completed. However, this introduces some complications.

Captures are only initiated when a request for a preview has been made. If you make your requests in serial and wait for responses before proceeding, then they’ll stack behind each other. This will multiply your overall load time.

Requesting multiple previews in parallel can be used to initiate capture for all desired configurations at once. In this case, your load time will be limited to the longest running query. Alternatively, you could choose to show those ready earlier as soon as they’re available.

At scale, this could lead to a large number of open waiting connections if these requests are made server-side. We can also run into client-side connection limits in the browser..

Working with browser connection limits

Requesting a single preview or two in parallel

If you’re only requesting a single preview or two in parallel, then you can skip this section on working with browser connection limitations. All common browsers allow this to occur unrestricted.

Requesting 3-6 images in parallel

You can safely ignore this unless you're concerned about the performance of your web application in legacy browsers where per-host connection limits will impact users.

However, if you’re concerned about the following browsers, we have a solution:

  • IE6 or IE7 — Maximum connections per host is 2
  • Opera 9.x — Maximum connections per host is 4
  • Safari 3 and 4 — Maximum connections per host is 4

To remedy this, we allow access to the API assets using domain sharding.

Requesting 7-10 images in parallel

At 7 concurrent connections many browsers start to reach per host limits. As above, see domain sharding.

Requesting 10+ images in parallel

When we reach 10 concurrent connections we start to hit all-host connection limits, particularly in Chrome. Domain sharding doesn’t stop our 11th request being queued, so it’s best to pre-request any images required before embedding.

Domain sharding

We allow GET requests against the API at custom subdomains, which allows you to circumvent browser per-host connections limits at the small cost of additional DNS lookups.

For instance, if the following hit a per-host connection limit:

<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb">
<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb">
<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb">
<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb">
<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb">
<img src="https://instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb">

The limit could be circumvented with:

<img src="https://OL2000.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb">
<img src="https://OL2002.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb">
<img src="https://OL2003.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb">
<img src="https://OL2007.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb">
<img src="https://OL2010.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb">
<img src="https://NOTES9.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb">

Note that the choice of subdomain is arbitrary. You only need to ensure that they are distinct. You could equally use:

<img src="https://1.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2000/thumb">
<img src="https://2.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2002/thumb">
<img src="https://3.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2003/thumb">
<img src="https://4.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2007/thumb">
<img src="https://5.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/OL2010/thumb">
<img src="https://6.instant-api.litmus.com/emails/ce6ba90f-cf28-4772-ab09-30a1d48a5e12/previews/NOTES9/thumb">

Pre-request

Pre-requesting allows for requesting that a capture (or set of captures) is initiated for specified configurations with an immediate (non-blocking) response.

Because the API guards against duplicate captures, this means that any requests queued due to browser connection limits will yield the preview as soon as the pre-requested capture has completed, rather than initiating then waiting the full duration of capture.

See the API method for further information.

Managing server-side connections

Downloading large volumes of raw image data or holding large numbers of open connections server-side could place unwanted burden on your infrastructure.

The simple solution to alleviate these concerns is to ensure capture requests are only made in-browser or in-app. This will distribute the bulk of the network and bandwidth strain.

If your use case doesn't allow for this approach, the bandwidth requirements are difficult to avoid. However, the number of open connections can be reduced by employing a pre-request along with a delay before attempting download of the captured previews.