Proxied resources are designed to be fast. With the possible exception of the very first time you access it, you will never have to wait more than 100ms for a response. This is largely possible by caching responses.

Cache updates are performed in the background so a developer never has to wait for data. By default, proxied resources are cached for 5 minutes. A background update is triggered during the first request after the 5 minutes has passed. Depending on how often your resource is requested, it may take somewhat more than 5 minutes before your proxy URL returns the latest data.

Even if the cache is “expired” (i.e. 5 minutes have passed) we will not expire old data until the new data is fetched. If the API doesn’t respond within 30 seconds, we will cache a blank result.

Refresh Intervals

Proxied resources are cached for 5 minutes by default. This interval is adjustable on a per resource basis: Simply change the “Refresh Interval” option when you enable your proxied resource.

Manually Refreshing

The default 5 minute interval is designed to prevent excess data usage and be a safe choice for complying with typical rate limits. However, if you need the latest data from the API and cannot wait until the next timed cache update, there are two ways to manually trigger an update. First, near the “Refresh Interval” option, there is a “Force Refresh” button that will expire the cache and trigger new data to be fetched. Second, you may send an HTTP PUT request to the proxy URL:

curl -i -X PUT -H "Api-Key: 14a2f4f3-4169-496e-a732-1fad06b9c34f"

If the request was successful, the URL will return response status 200. To prevent abuse, this update will only be successful every 15 seconds. If you send another PUT request within 15 seconds, the URL will return status 409.

Note that this refresh takes place in a background process, so your resource may not return the latest data immediately. The new data must be fetched and cached before it will be returned via the proxy URL. Also, since the query parameters affect caching (see next question), you must send the same parameters for the resource you want to manually refresh.

Cache Bypassing

You can access your resource directly bypassing the cache by providing a caching header called “Cache-Control” with the value “no-cache” when referencing your resource. This header instructs Fastly and Storyteller to ignore caching for this request thus forcing it to refetch the underlying resource. After the resource is fetched the cache is updated so the next request will have the latest data.

Caching Proxy Responses

You can access your resource directly and expose it to users if you wish, but to avoid using up all your request credits, you may want to cache it in your application. The data returned will not change within the 5 minute cache window, so there is no need to request a proxied resource more often than every 5 minutes. To let you know when the resource will update next, we provide “Cache-Control” and “Expires” HTTP headers in our responses. For example, if the headers returned are:

Cache-Control: max-age=296
Expires: Sat, 10 Aug 2013 01:37:25 UTC

then the resource will expire in 296 seconds, or at the timestamp. Use whichever is easier for you.