Sanity provides two APIs:
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.
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.
The API CDN is primarily meant to cache public query results, and as such the following requests are not cached:
OPTIONSrequests are rejected, including mutations (document writes)
- For G
raphQLwe also support
POSTrequests for reading
- Listeners are redirected to the live API (subscriptions to real-time updates)
- Cookies are removed from requests, including authentication cookies
- Requests with
Authorizationheaders 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.
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.
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