Lab 5 — Mediation¶
Goal: transform requests and responses in flight — extract values, call a side service, and reshape the body with JavaScript. ~25 min.
What you'll learn¶
ExtractVariablesfor pulling data out of payloadsServiceCalloutfor synchronous side calls (enrichment, lookup)JavaScriptpolicies for logic XML can't expressJSONtoXML/XMLtoJSONfor protocol translation
1. ExtractVariables — pull fields into flow variables¶
<ExtractVariables name="EV-ExtractPath">
<Source>request</Source>
<URIPath>
<Pattern ignoreCase="true">/orders/{orderId}</Pattern>
</URIPath>
</ExtractVariables>
GET /labs/orders/42 → variable urirequest.orderId = 42 (named
urirequest.{groupName} for URIPath patterns). Conditions and other policies
can now branch on it — e.g., route orders ≥ 10000 to a v2 backend.
For JSON payloads:
<ExtractVariables name="EV-ExtractBody">
<JSONPayload>
<Variable name="customerId">
<JSONPath>$.customer.id</JSONPath>
</Variable>
</JSONPayload>
</ExtractVariables>
2. ServiceCallout — synchronous side request¶
<ServiceCallout name="SC-FetchIP">
<Request clearPayload="true" variable="ipRequest">
<Set>
<Verb>GET</Verb>
</Set>
</Request>
<Response>ipResponse</Response>
<HTTPTargetConnection>
<URL>https://httpbin.org/ip</URL>
<Properties>
<Property name="success.codes">2xx</Property>
</Properties>
</HTTPTargetConnection>
</ServiceCallout>
The reply lands in ipResponse.content — extract $.origin and stamp it
onto the downstream response. Classic uses: token introspection at an IdP,
feature flags, per-request config lookups.
Callouts are blocking
A ServiceCallout holds the request open. Budget its latency into your
SLA, set success.codes deliberately, and pair with ResponseCache when
the data is cacheable (Lab 6).
3. JavaScript — the escape hatch¶
<Javascript name="JS-ShapeResponse">
<ResourceURL>jsc://shapeResponse.js</ResourceURL>
</Javascript>
// Runs in the response flow for /orders
var ctx = context; // Apigee's JS context object
var app = ctx.getVariable("developer.app.name") || "anonymous";
var dev = ctx.getVariable("developer.email") || "n/a";
var quota = {
allowed: ctx.getVariable("quota.Quota-PerApp.allowed"),
used: ctx.getVariable("quota.Quota-PerApp.used")
};
// Read the target's payload, wrap it in an envelope
var upstream = {};
try { upstream = JSON.parse(ctx.getVariable("response.content")); }
catch (e) { upstream = { raw: ctx.getVariable("response.content") }; }
ctx.setVariable("response.content", JSON.stringify({
message: "orders list",
app: app,
developer: dev,
quota: quota,
upstream: upstream
}));
ctx.setVariable("response.header.content-type", "application/json");
Key APIs:
| Call | Purpose |
|---|---|
context.getVariable(name) / setVariable |
read/write flow vars |
context.proxyRequest / targetResponse |
structured message access |
print(msg) |
writes to Trace's output panel — your console.log |
Rhino, not Node
The JS engine is Mozilla Rhino — ES5-ish, no fetch, no npm. HTTP calls
belong in ServiceCallout or httpClient (Apigee's object); heavy logic
belongs in a real service behind Apigee.
Exercise it¶
# GET /orders — response wrapped by JS, quota injected
curl -s "https://$APIGEE_HOST/labs/orders?apikey=$APIKEY" | jq
{
"message": "orders list",
"app": "labs-app",
"developer": "you@example.com",
"quota": {"allowed": 10, "used": 4},
"upstream": {...}
}
# Path extraction — /orders/{id}
curl -s "https://$APIGEE_HOST/labs/orders/42?apikey=$APIKEY" | jq '.orderId'
# → "42"
In Trace, click JS-ShapeResponse → the print() output appears in the
panel. Add print(JSON.stringify(upstream)) and redeploy to inspect payloads.
4. Bonus — JSON↔XML¶
<JSONtoXML name="J2X-OrderRequest">
<Source>request</Source>
<OutputVariable>request</OutputVariable>
<Options>
<Null>NULL</Null>
<TreatAsArray>
<Value unwrap="true">item</Value>
</TreatAsArray>
</Options>
</JSONtoXML>
Attach to a POST /orders flow pointing at a SOAP/XML backend — the classic
"REST front, legacy back" pattern. XMLtoJSON does the reverse on responses.
Experiments¶
- In
shapeResponse.js, setresponse.status.code = 201— the response flow can rewrite status codes downstream of the backend. - Point
SC-FetchIPat an unreachable host → faultServiceCallout→ see how the error surfaces (and think about where a FaultRule would degrade gracefully). - Chain mediation:
EV-ExtractPath→ condition a secondAssignMessagethat stampsX-Order-IDheader on the target request — watch it arrive at mocktarget via Trace.
Next¶
Lab 6 — Caching & Faults: cut latency and fail with consistent, client-friendly errors.