Understanding cache keys in Contensis

Caching is one of those invisible systems that quietly keep your sites fast, reliable, and resilient. In Contensis, cache keys make sure your users always get the latest content, without sacrificing performance. This article explains how it all works and how to enable it in your own framework.

Every time someone requests a page or calls an API, Contensis caches that response. The next person to make the same request gets it instantly, without waiting for the server to rebuild the result.

Caching isn’t just about speed; it’s also about resilience. If a data source temporarily fails – say with a 500 error or timeout – Contensis will still serve the cached version for up to 24 hours. That gives you time to fix the issue without your site going dark.

Caching gives you all the benefits of speed and stability – until something changes. The classic problem is cache invalidation: how do you update your cache instantly when content changes?

Contensis makes this simple. Any change in the CMS globally invalidates the affected resources within seconds. You get the best of both worlds – fast, distributed caching with immediate freshness. A genuine win-win.

If your site consumes the Contensis APIs directly using a client-side framework (no server-side rendering), you don’t need to do anything — our APIs handle cache invalidation automatically.

The same goes if you’re using the Contensis React Base project; the logic is built in.

However, if you’ve built your own delivery layer with server-side rendering, you’ll need to wire up cache invalidation yourself. Here’s how it works.

Every cached API request carries a set of cache keys – identifiers representing the data dependencies of that response.

For example, when you request /home from the Node API, we tag the response with a key for the node itself (its GUID) and for any linked entries. If /home changes, we invalidate those keys. The cached response is evicted automatically, and the next request fetches fresh data.

In short:

• Every API request is aware of its dependencies.
• When one of those dependencies changes, Contensis invalidates the cache – locally and across our global CDN.

Cache keys, and the cache invalidation they enable, allow us to deliver digital experiences that are both fast and up-to-date.

Some API calls, like broad searches, have more general dependencies.

A free-text search for “API” without a content type filter might return results from multiple content types. In this case, the request is tagged with a key such as any_content_update, meaning any new publication will invalidate it.

It’s not the most efficient key, but it’s rare, and Contensis still achieves around a 95% cache hit ratio across customer sites.

You don’t need to create cache keys manually. Just include the following header in your API request:

This tells the API to return the cache keys for that response.

You can test this using a tool like HTTPie — you’ll see the surrogate keys returned in the response headers.

• Only request surrogate keys server-side (during SSR). Don’t slow down user-facing requests.
• When your web app receives a request containing x-require-surrogate-key, return the keys in your own headers.
• When making server-side API calls, merge and de-duplicate the keys from all responses.
• Skip sending keys for normal requests – keep them lightweight.

Once this is set up, your URLs will automatically invalidate whenever content is updated or published in Contensis.

For reference, see the key logic in Contensis React Base:

• webApp.tsx
• headers.ts
• ContensisDeliveryApi.js

Once you’re set up, enabling caching is straightforward. For HTML responses, add:

The value is in seconds – this example caches the response for 60 seconds. You can extend this to 24 hours or more since Contensis will automatically invalidate pages when content changes.

If you don’t want to cache at all, simply use max-age=0.

Assets follow the same rules — automatic invalidation based on their URLs.

Images get an extra layer of intelligence. Each image URL includes an MD5 hash of the file’s bytes. That allows us to set long cache durations (great for your Google PageSpeed scores) because when the image changes, its hash – and therefore its URL – changes too.

For static files like CSS and JavaScript, use a build tool such as Webpack to generate unique filenames. This prevents old assets from being cached on users’ devices after deployments.

Caching works even for logged-in users.

When a user authenticates, they receive a cookie called ContensisCMSUsername, which contains their identity and expiry data. Using this, Contensis can determine which groups the user belongs to.

Your app should include a header such as:

Group IDs are pipe-separated (no leading or trailing pipes).

Once this header is present, our caching layer knows which pages to serve based on group permissions.

1. A user without a valid cookie is redirected to /account/login.
2. A user with a valid cookie has their identity and groups validated by Varnish.
3. We fetch the page.
4. If the groups match the x-contensis-viewer-groups header, the content is served and cached.
5. If not, the user is redirected to /account/accessdenied.

Contensis caching gives you speed, reliability, and simplicity – all without the headache of manual cache management.

You get:

• Automatic caching across APIs and delivery
• Global invalidation within seconds of publishing
• Smart dependency tracking through cache keys
• Built-in support for authenticated and static content

All of which means you can focus on building great digital experiences – while Contensis quietly keeps everything fast, fresh, and reliable behind the scenes.