Lab 6 — Caching & Faults¶
Goal: serve repeat GET /orders responses from ResponseCache, and
normalize every error into a clean JSON payload via FaultRules. ~20 min.
What you'll learn¶
ResponseCachelookup/populate semantics- Cache keys and why
client_idbelongs (or doesn't) in the key - The fault pipeline:
RaiseFault→FaultRules→DefaultFaultRule - Why error responses need their own CORS headers
Before you start
Re-read Core Concepts → Errors. In this lab you'll see every sentence of it happen.
ResponseCache¶
<ResponseCache async="false" continueOnError="false" enabled="true" name="RC-Orders">
<DisplayName>RC-Orders</DisplayName>
<CacheKey>
<Prefix/> <!-- (1)! -->
<KeyFragment ref="proxy.pathsuffix"/> <!-- (2)! -->
</CacheKey>
<ExpirySettings>
<TimeoutInSec>60</TimeoutInSec> <!-- (3)! -->
</ExpirySettings>
<SkipCacheLookup>request.header.x-no-cache Exists</SkipCacheLookup> <!-- (4)! -->
<SkipCachePopulation>response.status.code != 200</SkipCachePopulation> <!-- (5)! -->
</ResponseCache>
- Optional namespace string placed in front of the key. Empty here; set one
(e.g.
orders-v1) to avoid collisions when several policies share a cache. - The key is built from fragments joined together. Here: just the path
suffix, so
/ordersis one cache entry — shared by every caller. - Time-to-live: after 60 s the entry expires and the next call is a miss.
- A condition evaluated on lookup: if true, skip the cache read (forces a
backend call). The
x-no-cacheheader is the lab's escape hatch. - A condition evaluated on populate: only store 200s. Without it a transient 500 would be cached and replayed for the full TTL.
Attachment is a pair — lookup on the way in, populate on the way out:
<Flow name="get-orders">
<Request>
<Step><Name>VA-CheckAPIKey</Name></Step>
<Step><Name>Quota-PerApp</Name></Step>
<Step><Name>AM-StripKey</Name></Step>
<Step><Name>RC-Orders</Name></Step> <!-- (1)! -->
</Request>
<Response>
<Step><Name>JS-ShapeResponse</Name></Step>
<Step><Name>RC-Orders</Name></Step> <!-- (2)! -->
</Response>
</Flow>
- Lookup. On a hit the target call is skipped and the response flow begins immediately, carrying the cached body.
- Populate. The same policy name in the response flow stores the
response — after
JS-ShapeResponse, so what is cached is the already shaped envelope.
Cache hits skip the backend
In Trace you'll see the request phase end early and no target round-trip. That's your proof the cache works.
Exercise it¶
Predict
Call /orders with x-no-cache: 1 (miss), then twice more without the
header within 60 s. Which call(s) show "hit (edge)"? Does the quota
counter go up on hits?
Answer
Calls 2 and 3 are hits. The quota counter does increase on hits —
Quota-PerApp runs before the cache lookup.
# First call — miss, hits the backend
curl -s "https://$APIGEE_HOST/labs/orders?apikey=$APIKEY" \
-H "x-no-cache: 1" | jq .cache
# Second call — hit, served at the edge
curl -s "https://$APIGEE_HOST/labs/orders?apikey=$APIKEY" | jq .cache
(The bundle's JS stamps the cache field from
responsecache.RC-Orders.cachehit.)
Compare latencies:
curl -s -o /dev/null -w "miss: %{time_total}s\n" \
"https://$APIGEE_HOST/labs/orders?apikey=$APIKEY" -H "x-no-cache: 1"
curl -s -o /dev/null -w "hit: %{time_total}s\n" \
"https://$APIGEE_HOST/labs/orders?apikey=$APIKEY"
Edge hits shave the target round-trip entirely.
Key design is a security decision
The key here is just pathsuffix — every app shares the cached body. If
responses are per-user, add <KeyFragmentref="verifyapikey.VA-CheckAPIKey.client_id"/> — or better, never cache
personalized data. Cache poisoning across tenants is a real bug class.
Here the cached body even contains the first caller's app and
developer — a leak you can see for yourself by calling with a second
app's key.
Fault pipeline¶
Deliberately break things and normalize the output. This is the bundle's actual fault section, condensed:
<FaultRules> <!-- (1)! -->
<FaultRule name="auth-faults">
<Step><Name>AM-Error401</Name></Step> <!-- (2)! -->
<Condition>(fault.name = "FailedToResolveAPIKey") or
(fault.name = "InvalidApiKey") or
(fault.name Matches "*Token*")</Condition> <!-- (3)! -->
</FaultRule>
<FaultRule name="throttled">
<Step><Name>AM-Error429</Name></Step>
<Condition>(fault.name = "QuotaViolation") or
(fault.name = "SpikeArrestViolation")</Condition>
</FaultRule>
</FaultRules>
<DefaultFaultRule name="fallback">
<Step><Name>AM-Error500</Name></Step> <!-- (4)! -->
<Condition>fault.name != "RaiseFault"</Condition> <!-- (5)! -->
</DefaultFaultRule>
- Evaluated top to bottom only when something faulted; first rule with a true condition runs and the rest are skipped.
- The response builder: a normal policy (an
AssignMessage) that sets body and status. - Match on
fault.name. Look it up in Trace (or the fault table). Wildcards cover families of names. - Catch-all so clients never see Apigee's default fault payload.
- Don't overwrite faults you raised on purpose (
RaiseFaultalready builds a precise response).
<AssignMessage async="false" continueOnError="false" enabled="true" name="AM-Error401">
<DisplayName>AM-Error401</DisplayName>
<Set>
<Headers>
<Header name="Access-Control-Allow-Origin">{kvm.cors.origin}</Header> <!-- (1)! -->
</Headers>
<Payload contentType="application/json">
{"error": {"code": "UNAUTHORIZED", "message": "valid credentials required", "fault": "{fault.name}"}} <!-- (2)! -->
</Payload>
<StatusCode>401</StatusCode>
</Set>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <!-- (3)! -->
<AssignTo createNew="false" type="response">response</AssignTo>
</AssignMessage>
- The PostFlow (
AM-CORS-Headers) doesn't run on faults, so the error policy must add the CORS header itself — otherwise browsers show an opaque "CORS error" instead of your 401. {fault.name}is only available while fault handling runs. Echoing it helps clients and logs; consider omitting internals in production.- On an error path a second failure (say the KVM wasn't loaded because the spike arrest faulted first) would hide the first. Be lenient here.
And RaiseFault to trigger one yourself — the bundle rejects POST /orders
bodies that lack customerId:
<RaiseFault async="false" continueOnError="false" enabled="true" name="RF-MissingCustomer">
<DisplayName>RF-MissingCustomer</DisplayName>
<FaultResponse> <!-- (1)! -->
<Set>
<Payload contentType="application/json">
{"error": {"code": "BAD_REQUEST", "message": "customerId is required"}}
</Payload>
<StatusCode>400</StatusCode> <!-- (2)! -->
</Set>
</FaultResponse>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>
- The response to send. It has the same
Setvocabulary asAssignMessage. - A 4xx because the client erred. RaiseFault is how you turn a validation failure (not a system failure) into a precise response.
Exercise it¶
# Trigger the RaiseFault
curl -s -X POST "https://$APIGEE_HOST/labs/orders?apikey=$APIKEY" \
-H 'content-type: application/json' -d '{"item":"widget"}' | jq
# Anonymous → your normalized 401 (not Apigee's default fault)
curl -s "https://$APIGEE_HOST/labs/orders" | jq
{"error": {"code": "UNAUTHORIZED", "message": "valid credentials required", "fault": "FailedToResolveAPIKey"}}
Experiments¶
- Drop the
x-no-cachebypass header, call twice in Trace — confirm the target step disappears on the hit. - Set
TimeoutInSecto 5 and watch the hit flip back to a miss between calls. - Remove
<SkipCachePopulation>response.status.code != 200</...>— what class of bug does that invite? (Error responses cached for the TTL.) - Add the
<KeyFragment ref="verifyapikey.VA-CheckAPIKey.client_id"/>from the warning above, redeploy, call with two apps and compareapp. - Delete the
ConditionfromDefaultFaultRule, redeploy, and re-run theRaiseFaultcurl. What status do you get now and why? - Add a FaultRule matching
ExecutionFailedthat degradesSC-FetchIPfailures instead of failing the request (hint:continueOnErroron the callout is the simpler alternative — compare them).
Check yourself¶
1. Why is the same policy name listed twice in the get-orders flow?
One attachment performs the cache lookup (request phase), the other the populate (response phase). It's one policy file, two attachment points.
2. A cached response contains \"app\": \"labs-app\". Another tenant calls and receives it. What two fixes?
Add client_id to the cache key, or don't cache personalised responses
(shape them after the cache with a response-phase policy that runs on both
hits and misses).
3. Why do the error policies set Access-Control-Allow-Origin themselves?
Because the PostFlow that normally adds it is skipped when a fault occurs.
4. Order the evaluation: DefaultFaultRule, FaultRule #2, FaultRule #1.
1, then #2 (first match wins), and the DefaultFaultRule only if neither¶
matched.
5. When would you choose RaiseFault over just letting a policy fail?
For your own validation rules (bad body, business-rule violations) where you want a precise status/message rather than a policy's built-in fault.
Next¶
Lab 7 — CORS & KVM: browser-safe APIs and per-environment configuration without redeploys.