Caching

There are two caches in front of your traffic, and they are easy to tell apart because each reports itself in a response header:

Nothing else is cached in a way you can observe or should reason about. If a response carries neither header, it was not served from either cache.

The gateway response cache

API responses are cached only when the capability serving them opts in. There is no blanket TTL on api.revenexx.com: a capability with no cache declaration is never cached, which is the default and the right default for anything that writes.

When a capability does opt in, the response carries X-Cache:

curl -sI https://api.revenexx.com/v1/markets \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." | grep -i x-cache

X-Cache: HIT

HIT means the response came from the cache, MISS means it was computed. A response with no X-Cache header at all is from a capability that does not cache.

Two properties matter if you are consuming these responses:

• Entries are scoped per caller by default. A cached response is keyed to the identity that asked for it, so a permission-filtered list or a customer-specific price cannot be served to a different caller. Only data that genuinely does not depend on who asked — a tenant's markets, currencies, locales, tax classes — is shared across callers of a tenant.
• Writes invalidate. A capability declares which entities drop its cached entries, so changing a market clears the cached market list for that tenant rather than leaving you to wait out a TTL.

If you are building an app and deciding what your own capabilities should cache, the declaration and its fields are documented in Caching under App Studio. This page is about what you observe as a caller.

The edge cache

For a domain you have pointed at the edge, each point of presence caches what it can and reports the result in X-Edge-Cache:

X-Edge-Cache: HIT

The values are HIT, MISS, EXPIRED, STALE, UPDATING and BYPASS.

• Entries live for one hour, then get revalidated.
• Only 200 and 302 responses are cached.
• While an entry is being revalidated, or if the origin errors or times out, the existing entry keeps being served — you will see UPDATING or STALE. This is why a brief origin problem does not take cached content down with it.
• The cache key for a /cdn/ asset includes the query string, so each distinct set of image transform parameters is its own entry.

There is no purge API. To force a change live immediately, change the URL — a new path or a new set of transform parameters is a new key and is fetched fresh.

api.revenexx.com is answered by the origin, so its responses never carry X-Edge-Cache.

Caching in the client

Responses carry standard HTTP cache directives, and they are worth honouring rather than working around:

• Cache-Control: private marks a response that may be stored by the client that asked for it but must not be held in a shared cache. Anything shaped by who is signed in gets this.
• Cache-Control: no-store marks a response that must not be stored at all.
• Vary names the request headers a cached response depends on. A response that varies by credential must not be reused across users.

If you are putting your own cache or reverse proxy in front of revenexx, respect these three. A shared cache that ignores private and Vary is the way a permission-filtered response reaches the wrong user, and neither cache described above can protect you from that.

Related

• Content delivery — what the edge cache does for assets under your own domain
• Caching — declaring the cache for a capability you are building
• API usage — the other response headers worth reading