Builder’s Content API is designed for speed and resilience, but performance depends on how requests are structured.
This guide explains how to maximize cache efficiency, avoid patterns that bypass protection, and set up an optional intermediate caching layer for business-critical workloads.
This guide shows how to:
- avoid patterns that bypass protective caching
- keep cache hit rates high for speed and resiliency
- optional: adopt an intermediate cache for mission-critical workloads
cachebust=true bypasses protective edge caching. Reserve it for controlled maintenance tasks only, such as webhook-triggered prefetch jobs. Remove it from all production user requests.
Builder’s CDN uses stale-while-revalidate and stale-if-error. That lets caches serve immediately from a recent copy while updating in the background, and it shields users during origin hiccups.
Builder’s CDN cache keys include the full URL. Fewer unique URLs means more cache hits and faster, safer responses.
Good examples: audience=menswear, isNewUser=true, region=us, plan=premium
Avoid per-visitor or highly unique values like visitorId, timestamps, random tokens, long free-text.
- Keep attribute value sets small and well defined.
- Prefer enums or booleans over free-text.
- Keep parameter order consistent to improve de-dupe in intermediate caches.
- Do not include PII in query params.
For businesses where even an occasional moment of degraded performance can be business-critical, you may want to consider an intermediate cache.
To have zero reliance on Builder at request time, you can place your own cache between your app and Builder. All production traffic then hits your cache only.
Your cache serves the last known good response and refreshes asynchronously. If Builder is slow or returns errors, users keep getting the cached copy until refresh succeeds.
- Cache key: include model name plus only low-cardinality
userAttributes - TTL: set a reasonable
max-ageand allow stale reads during refresh - Refresh: revalidate asynchronously in the background
- On error: serve stale from your cache
To use your own intermediate layer, switch SDK fetches (builder.get(...), fetchOneEntry(...)) to direct REST calls to our Content API. The SDKs are thin wrappers; using HTTP directly makes it easy to route through your cache.
- Remove
cachebust=truefrom runtime requests - Use a small set of stable
userAttributesvalues - Add an intermediate cache if you need 0 reliance on our APIs at runtime