Caching Layer Overview For View API

Arc XP’s headless CMS features a robust caching layer that provides you with significantly faster content delivery. By strategically storing frequently accessed content closer to the end-user, the caching layer drastically reduces latency, ensuring a seamless browsing experience. Caching optimizes load times, leading to quicker time to first byte and smoother interactions. Moreover, by alleviating the strain on back-end servers, caching enhances scalability and reliability, even during traffic spikes. In essence, a caching layer complements the agility of a headless CMS, empowering users with speed and responsiveness.

This caching layer is crucial for high-traffic online publications and magazines, ensuring that readers access content quickly and seamlessly.

Understanding The Caching Layer

Dynamic Cache Clearing

Arc XP incorporates a dynamic caching system with cache tags to ensure near-instant content updates when you publish. Here’s a brief overview of how it works:

• Automatic endpoint updates: When content is updated, such as publishing a story or changing a website URL, Arc XP automatically clears related /by-id and /by-url endpoints based on the cache tags linked to the content objects.
• List endpoint management: The system evaluates the data within content objects to determine which list endpoints are affected. For example, adding a foobar tag to a story leads to the automatic clearing of the /by-tag?slug=foobar endpoint, ensuring that the new article is visible in the search results.
• Comprehensive coverage: This caching logic extends to various elements, including authors, sections, and websites, maintaining the efficiency and relevance of data across all endpoints supported by Arc XP’s headless configuration.

Reference updates supported

Arc XP’s caching layer also includes referent updates, enabling automated cache clearing for different object types. Review the following table to understand the supported referent update types.

Reference updates	Supported
Update or delete an image or gallery in Photo Center	Yes
Update or delete a video in Video Center	Yes
Update or delete an author in Author Service	Yes
Update or delete a story through Draft API	Yes
If a story is updated, the collection under which it is included, manually or via backfill by section or tag, will also be updated	Yes
Update even triggered for a story based on an update to an image, gallery, video, or author	Yes
Updating or deleting a section within Site Service	No
Updating or deleting a site within Site Service	No

Time-to-Live (TTL) configuration

Arc XP’s headless system updates content dynamically based on publishing events, optimizing TTL values for peak performance at the network edge. Here’s a concise overview of how it manages caching:

• Visibility of TTL values: The current TTL for any object is indicated in the x-arc-ttl response header, which is visible on URLs returning HTTP 200 response. The TTL helps users understand the cache duration for content that Arc XP serves directly. For other codes within 4xx and 5xx status codes, the responses are also cached for an appropriate amount of time based on internal assessment.
• Downstream cache control: Arc XP sets standard cache-control headers on responses to manage how downstream proxy-caches handle cached content. Because you cannot clear these external caches like internal caches, controlled settings ensure consistent content behavior across different caching layers.

Content age configuration

Arc XP sets a last-modified response header containing the time that the response was fetched and placed into cache. Use this value to determine when a "search" was executed or when a content object was retrieved.

Rate limit configuration

The number of non-cached responses that can be served through a headless content delivery system is limited. We categorize our endpoints into two distinct types, and rate limits are applied differently for these types:

• List endpoints: The system use list endpoints to return multiple entries based on requested parameters and for searches. Examples include endpoints like /by-author, /by-tag, etc.
• Single endpoints: The system uses single endpoints to retrieve information about a specific story, author, etc.

How caching affects rate limits

When content is updated in Arc XP, two steps occur in order for the API response to be updated:

1. The prior API response is cleared from cache: This process takes about one minute, plus additional time for rendering, for a publishing activity your organization undertakes, like updating a story.
2. The updated API response is requested, retrieved, and stored in cache: This happens the next time the API response is requested. This first request of the updated API response counts toward your rate limit. Subsequent requests are cached and do not count toward your rate limit. 

In most cases, these two events happen in quick succession. For example, if an author updates a breaking news story that thousands of users are currently reading on your website, it is cleared from cache (step 1) and the cache is repopulated (step 2) within seconds, because many users are currently accessing this content.

However, in some edge cases, there might be a significant delay between when content is cleared (step 1) and when the new API response is requested (step 2). For example, an author updates an old story that no site visitors are currently reading and that appears on the 99th page of a /by-tag endpoint. The API response is cleared from cache immediately (step 1), but the next time this API response is requested (step 2) may not be until a bot crawls hundreds of pages deep into your site’s tag pages weeks later (because it is an old story that no real users are actively visiting, only bots). The rate limit is applied in step 2, which in this scenario is much later than the actual publishing event.

Handling rate limits

If rate limits are triggered and the content has previously been delivered by our system (and the object was not evicted from cache), a "stale" response is served instead of showing an error message to the end user. However, if the content has never been requested before, the user receives the 429 error message.

Cache clearing cases to be aware of

Dynamic curation limits in collections

The ability to dynamically curate collections through tags or sections is a key feature of our headless CMS. For caching efficiency, the system presently processes only the first 20 tags or sections. Collections that incorporate tags or sections beyond this configuration do not automatically trigger a cache update. To manage this, users may manually refresh the collection. Optimizing the number of tags or sections to 20 or fewer is advisable for best performance.

Pagination drift

All list endpoints in our system that utilize filter criteria are subject to what we call pagination drift. These endpoints include:

• stories (depends on website parameter)
• stories/by-author
• stories/by-section
• stories/by-tag
• collections/by-id (that have dynamic curation for stories)
• collections/by-alias (that have dynamic curation for stories)

When a cached page is created and a user later updates the story by changing any of the filter parameters, such as removing a tag, moving the story to a different section or website, or changing the author, the updates will only be reflected on the specific page where the story currently resides. As a result, the cached versions of the preceding and following pages will remain unchanged. This can lead to instances where users may encounter duplicate or missing documents as they navigate from one page to another. To solve this issue, users just need to publish a story that meets the author, section, or tag criteria; this will clear the cache of the drifted page.

Frequently Asked Questions (FAQs)

What happens when the content is updated? How quickly does the change reflect on the website?

Any content updates on Single and List endpoints are propagated and visible to the end-users within approximately one minute, due to our cache clearing.

Do we have a TTL value?

The Arc XP team is continuously optimizing the TTL values to ensure that content remains fresh and available. You can find the current configured TTL value through the x-arc-ttl response header.

How does the stale cache response work in case of rate limiting?
If your site reaches the rate limit, Arc XP automatically serves a stale cached version of the requested content. This ensures that your site remains accessible to users, albeit with slightly older content, until the rate limit is lifted.

Can we customize the TTL settings?

No, we don’t offer customization options for TTL because cache clearing is triggered when a publish, republish, or delete event occurs.