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 backend 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 unless there is a good reason not to.

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.

Cache Policy

The API CDN is primarily meant to cache public query results, and as such the following requests are not cached:

  • Non-GET/HEAD/OPTIONS requests are rejected, including mutations (document writes)
  • For GraphQL we also support POST requests for reading
  • Listeners are redirected to the live API (subscriptions to real-time updates)
  • Cookies are removed from requests, including authentication cookies
  • Requests with Authorization headers are rejected, i.e. authenticated requests
  • 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.

Invalidation

The API CDN currently caches requests for 1 week, and the entire cache for a dataset is invalidated whenever there is a write to a non-draft document in the dataset. Invalidation may take up to 30 seconds to propagate fully, and clients may be served stale data while new data is fetched in the background for an additional 1200 seconds.

We will serve stale content if the backend serves an error, if the object is less than two hours old.

Additionally, data is cached throughout Google's worldwide CDN for 120 seconds to better serve high-volume projects.

We also use Google's global load balancers to reduce initial connection setup latency, as well as their globally distributed DNS servers for fast DNS lookups.

We previously had skewed the API CDN towards delivering fresh data, at the cost of latency of fetching new data. Now we try to deliver data fast but slightly stale instead, prioritizing user experience over freshness.

Locations

Sanity currently has CDN nodes in these locations:

  • Asia: Hong Kong
  • Australia: Sydney
  • Europe: Belgium
  • South America: Sao Paolo, Brazil
  • United States: Oregon, Iowa and Northern Virginia

Was this article helpful?