Implementing API cache control

This guide explains how to implement API cache control. Once you've enabled API caching, and ensured purging works properly with your cached data, you can set up specific headers like Cache-Control and Surrogate-Control to change when data is cached.

Understanding Cache-Control headers

In general, we assume that GET requests are cached and PUT, POST, and DELETE requests are not. For an ideal REST API, this rule works well. Unfortunately, most APIs are far from ideal and require additional caching rules for some requests.

For these reasons, it's a good idea to set Cache-Control headers when migrating APIs to Fastly. Cache-Control, as defined by RFC 7234 (the HTTP specification), includes many different options for appropriate handling of cached data. Specifically, Cache-Control headers tell user agents (e.g., web browsers) how to handle the caching of server responses. For example:

• Cache-Control: private
• Cache-Control: max-age=86400

In the first example, private tells the user agent the information is specific to a single user and should not be cached for other users. In the second example, max-age=86400 tells the user agent the response can be cached, but that it expires in exactly 86,400 seconds (one day).

Fastly respects Cache-Control headers by default, but you can also use another proxy-specific header: Surrogate-Control. Surrogate-Control headers are similar to Cache-Control headers, but provide instructions to reverse proxy caches like Fastly. You can use Cache-Control and Surrogate-Control headers together. For more information about Cache-Control and Surrogate-Control headers, see our documentation on cache freshness.

An updated example

Let's take a look at how the Cache-Control headers could be used in our original example, the comments API. Recall the API endpoint that provided a list of comments for a given article:

GET /article/:article_id/comments

When a user submits a comment for a given article, the response from this endpoint will be purged from the Fastly cache by the comment model. It's hard to predict when content will change. Therefore, we'd like to ensure the following:

1. If the content doesn't change, it should stay cached in Fastly for a reasonable amount of time.
2. If the content does change, it should not be cached by the client longer than it needs to be.

The goal is to ensure that API responses will reach clients in a timely manner, but we also want to ensure that clients always have the most up-to-date information. The first constraint can be solved by using the Surrogate-Control header, and the second constraint can be solved by using the Cache-Control header:

Surrogate-Control: max-age=86400
Cache-Control: max-age=60

These headers tell Fastly that it is allowed to cache the content for up to one day. In addition, the headers tell the client that it is allowed to cache the content for 60 seconds, and that it should go back to its source of truth (in this case, the Fastly cache) after 60 seconds.

Implementing cache control

Migrating APIs isn't easy, even for experienced teams. When migrating an API to Fastly, we recommend separating the task into three strategic endpoint migrations to make the process more manageable while still maintaining the validity of the API as a whole.

Preparing the API

To ensure that the API bypasses the cache during the piecewise migration, we must have every API endpoint return a specific control header:

Cache-Control: private

This header tells Fastly that a request to any endpoint on the API should bypass the cache and be sent directly to the origin. This will allow us to serve the API via Fastly and have it work as expected.

Serving traffic with Fastly

The next step is configuring a Fastly service to serve the API's traffic. After you save the configuration, there will be an immediate speed improvement. This happens because Fastly's cache servers keep long-lasting connections to the API's origin servers, which reduces the latency overhead of establishing multiple TCP connections.

Migrating endpoints

Now we can implement instant purge caching for each cacheable API endpoint, one at a time. The order in which this is done depends on the API, but by targeting the slowest endpoints first, you can achieve dramatic improvements for endpoints that need them the most. Because each endpoint can be worked on independently, the engineering process is easier to manage.

Excluding endpoints

The last step is deciding which API endpoints you don't want Fastly to cache. To disable caching for endpoints, you'll need to add new conditions for the endpoints. As you learned in Preparing the API, using the Cache-Control: private header is another option for disabling caching.