Happening this week! Hear how Amplitude built a self-serve marketing engine to drive growth 🚀

API CDN

Description of the CDN-distributed, cached version of the Sanity API.

Sanity provides two APIs:

  1. api.sanity.io: the live, uncached API. This is the default and will always give you the freshest data, but requests will be slower because they need to reach our back end on every request. Requests are also more costly because they will trigger more computation on our servers.
  2. apicdn.sanity.io: the CDN-distributed, cached API, which is an opt-in feature that will give you very fast responses to requests that have been cached. We encourage most users to use this API for their front-ends if you expose your API to end users. For static builds you are better off using the live uncached API, to always get the latest version.

To use the API CDN, simply use apicdn.sanity.io instead of api.sanity.io. Most clients provide a useCdn option that makes this switch seamless.

Gotcha

The API CDN only supports the /data/query path—its purpose being to cache query results across the globe for the benefit of your end users.

Protip

If you are going to fetch content from a browser, you should be using the API CDN. That is the way to build something that can scale.

Cache Policy

The API CDN is primarily meant to cache query results for end users:

  • We cache GET, HEAD and OPTION requests.
  • We cache POST for /graphql and /data/query as these endpoints are readonly.
  • Maximum HTTP POST size is 300 KB.
  • We reject all other POST since they can contain mutations.
  • Listeners are redirected to the live API (subscriptions to real-time updates)
  • Cookies are removed from requests, including authentication cookies
  • Responses larger than 10 MB are not cached
  • Non-200 responses are not cached

All official clients will automatically fall back to using the live API where appropriate.

Authentication

We cache authenticated requests in the API CDN, by using the authentication token as a cache key. This way you get a unique cache entry per authentication key/url combination.

If you use Sanity Client 3.0.0 and above it now supports caching of authenticated requests against the API CDN.

Invalidation

The entire cache for a dataset is invalidated whenever there is a write to a non-draft document in the dataset. Invalidations may take up to 60 seconds to fully propagate.

In some edge cases for rarely used queries, you can experience a delay of up to 120 seconds. (We serve a stale version of a document while we fetch a new version in the background, and it can be up to 60 seconds stale, see "Stale while revalidate" below.)

If the back end serves an error, we will serve stale content if the content is less than 2 hours old.

Stale while revalidate

If the object in the cache has expired less than 60 seconds ago, our API CDN will serve the old object while it fetches a new one in the background. The upside is that most uses of the API CDN will be served fast, from cache, and the content will be reasonably fresh.

The downside to this is that some use cases, such as sites with little traffic, could end up with stale content on first load. We recommend using the API directly in these cases.

Stale if Error

If the API CDN receives an error from the API it will use the last known good response if it is fresher than 2 hours.

Locations

Sanity currently has CDNs for the API in these locations:

  • Asia
    • Hong Kong
    • Mumbai, India
  • Oceania
    • Sydney, Australia
  • Europe
    • Saint-Ghislain, Belgium
  • South America
    • São Paulo, Brazil
  • North America
    • Oregon, United States
    • Iowa, United States
    • Northern Virginia, United States

In addition, we utilize a short-lived global CDN in front of our own CDN. This extra CDN has points of presence in multiple locations on all continents. The short-lived global CDN does not cache private datasets or queries using the POST method.

Was this article helpful?