Content Delivery API

Cache Tags Overview

DatoCMS Cache Tags help optimize your website or app's caching. They allow developers to simply tag webpages with unique identifiers, so when the content from the CMS is updated, these tags can trigger an immediate and precise cache invalidation only for the pages that actually include that content, and need to be regenerated.

The main benefits include:

Visitors can instantly view the most updated version of the content, while maintaining the benefits of completely static and cached content.
Hosting expenses and DatoCMS resource usage can be dramatically reduced thanks to a precise caching mode that does not rely on time-based invalidation methods, or a total invalidation of the entire site when anything changes.
It entirely relieves the developer of the duty to manage cache invalidation, a task which is instead taken care of by DatoCMS itself.

For a more comprehensive understanding of DatoCMS cache tags and the problem it solves, we recommend reading the feature's announcement which provides some additional background.

How does it work?

Implementing cache tags on your app is a three-step process:

Ask the Content Delivery API to return the cache tags associated with each query, by adding an X-Cache-Tags header to your GraphQL requests;
Mark every page your website produces with the cache tags you received;
Implement an endpoint that invalidates those tags when DatoCMS sends them to you through a webhook.

All three steps are designed to be quite straightforward to implement, allowing you to benefit from the advantages this method offers in a very short time. The rest of this section covers them in detail:

Cache tags in CDA responses — how to request cache tags, how they are encoded, and the limits every response respects.
Integrating cache tags in your project — how to apply the tags and purge them, first with any server behind a CDN, then with popular frameworks and hosting platforms.
The cache tags invalidation webhook — how DatoCMS tells you what to invalidate, and what the payload looks like.

What will be the final cache hit ratio?

It is very difficult to answer this question precisely, as it is connected to a large number of factors including the type of site traffic, the frequency of content updates, the content present in your pages, the GraphQL queries you execute, and the reliability of the cache in the selected framework and hosting.

Sometimes, it's simple to guess which pages will be invalidated when a content change occurs: for instance, if a blog's homepage showcases the latest posts, it's clear that adding a new post on DatoCMS will invalidate the homepage. Another straightforward example: let's say you have a query that pulls content for your website's navigation bar: any pages including that navigation bar need to be invalidated when the query creates new content.

Other cases are less obvious to grasp: suppose that a post can belong to some categories, maybe more than one category. Which are the pages invalidated when an editor changes a post's categories?

So, without being able to predict the actual result in terms of hit ratio, it is certainly possible to say this:

Regardless of the frequency of invalidation, a superior result will still be achieved with DatoCMS Cache Tags, compared to redeploying the entire website, invalidating all pages for each individual content change.
The benefits of cache tags increase as the number of pages on a website grows.