Proxy Anatomy¶
Everything in Apigee hands-on work reduces to three ideas: bundles, endpoints, and flows. Get these right and every policy doc makes sense.
By the end of this page you can...
- Name every file in a bundle and say what it does.
- Say, for any policy, when it will run relative to every other policy.
- Explain why a fault skips the PostFlow.
- Read a ProxyEndpoint top to bottom and predict which flow handles a URL.
New to the vocabulary? Skim Core Concepts first.
The bundle¶
An API proxy is a directory of XML (plus optional JS/Python/Java resources)
called a bundle. apigeecli zips and uploads it; Apigee stores it as an
immutable revision.
labs-proxy/
└── apiproxy/
├── proxies/
│ └── default.xml # ProxyEndpoint — the "front door"
├── targets/
│ └── default.xml # TargetEndpoint — the "backend"
├── policies/
│ ├── AM-SetHello.xml # one file per policy instance
│ ├── VerifyAPIKey-Check.xml
│ └── ...
└── resources/
└── jsc/
└── shapeResponse.js # code called by JavaScript policies
Policy file names
The file name in policies/ must match the <Policy name="...">
referenced in a flow <Step>. AM-SetHello.xml ↔ <Step><Name>AM-SetHello</Name>.
Two endpoints¶
| Endpoint | File | Faces | Defines |
|---|---|---|---|
| ProxyEndpoint | proxies/default.xml |
The client | Base path, virtual host, request/response flows |
| TargetEndpoint | targets/default.xml |
The backend | Target URL, connection/SSL config, request/response flows |
Clients hit the ProxyEndpoint's BasePath (/labs); the TargetEndpoint
forwards to the backend URL (mocktarget.apigee.net).
Flows — where policies execute¶
Each endpoint has a request pipeline and a response pipeline, divided into
PreFlow, PostFlow, and conditional Flow blocks. Policies attach as
<Step>s and execute in document order.
| Block | Runs when | Typical contents |
|---|---|---|
| PreFlow | always, first | rate limiting, auth that covers every path, config loading |
| Flow (conditional) | only the first one whose <Condition> is true |
path/verb specific policies |
| PostFlow | always, last | response decoration (CORS headers, logging) |
| PostClientFlow (response only) | after the response is sent | message logging — can't change the response |
Why the response phase runs in reverse
The response travels back through the same two endpoints it came through, target first, proxy last. Anything you attach to the proxy response therefore sees the final, target-processed message — which is why mediation (reshaping) lives there.
sequenceDiagram
participant CL as Client
participant PE as ProxyEndpoint
participant TE as TargetEndpoint
participant BE as Backend
CL->>PE: request
Note over PE: Request PreFlow<br/>(security, quota — run for EVERY call)
Note over PE: Conditional flows<br/>(matched on path/verb/vars)
PE->>TE: transformed request
Note over TE: Request PreFlow + conditional flows
TE->>BE: HTTP request
BE-->>TE: HTTP response
Note over TE: Response flows
TE-->>PE: response
Note over PE: Response flows<br/>(mediation, cache write)
PE-->>CL: response
<!-- simplified teaching excerpt of a ProxyEndpoint -->
<ProxyEndpoint name="default"> <!-- (1)! -->
<PreFlow name="PreFlow"> <!-- (2)! -->
<Request>
<Step><Name>VerifyAPIKey-Check</Name></Step> <!-- (3)! -->
<Step><Name>Quota-PerApp</Name></Step> <!-- (4)! -->
</Request>
<Response/>
</PreFlow>
<Flows> <!-- (5)! -->
<Flow name="get-orders">
<Condition>(proxy.pathsuffix MatchesPath "/orders") and (request.verb = "GET")</Condition> <!-- (6)! -->
<Request/>
<Response>
<Step><Name>JS-ShapeResponse</Name></Step> <!-- (7)! -->
</Response>
</Flow>
</Flows>
<PostFlow name="PostFlow"> <!-- (8)! -->
<Request/><Response/>
</PostFlow>
<HTTPProxyConnection>
<BasePath>/labs</BasePath> <!-- (9)! -->
<VirtualHost>default</VirtualHost> <!-- (10)! -->
</HTTPProxyConnection>
<RouteRule name="default"> <!-- (11)! -->
<TargetEndpoint>default</TargetEndpoint> <!-- (12)! -->
</RouteRule>
</ProxyEndpoint>
- The container for everything the client-facing side does.
nameis just an identifier. - PreFlow: unconditional, always first. No
<Condition>allowed here. - First policy to run for every request — authenticate before spending anything else.
- Second: Quota. Listed after the key check because it needs the identity the key check produces. Steps run in document order, so the order is the logic.
- Container for conditional flows. Evaluated top to bottom after PreFlow; first true condition wins.
- Two conditions joined with
and.proxy.pathsuffixis what comes after/labs;request.verbis the HTTP method. - Attached in the Response half: runs on the way back to the client,
after the target replied, so
response.contentis the backend's body. - PostFlow: always runs last in this endpoint, whichever flow matched. Empty here — present so the structure is explicit.
- The URL prefix that selects this proxy. Together with the environment group hostname it forms the public URL.
- Legacy name for "the listener this proxy attaches to" — in Apigee X the
hostname comes from the environment group, so it is always
default. - Routing decision made after the proxy request flow completes. Rules are checked in order; an unconditioned rule is the fallback and must be last.
- Names the TargetEndpoint file to hand the request to. Omit it and the rule means "no backend" (used by edge-only endpoints in the labs).
Key details:
proxy.pathsuffixis the path after theBasePath— for/labs/ordersthe pathsuffix is/orders.- First matching conditional flow wins — order your
<Flow>blocks deliberately. A<Flow>with no<Condition>matches everything. RouteRuledecides which TargetEndpoint receives the request; you can add conditions here to route/v1and/v2to different backends.
Flow variables¶
Apigee maintains a per-transaction variable bag. Policies read and write these; conditions evaluate them. You'll use these constantly:
| Variable | Contains | Set by |
|---|---|---|
request.verb, request.uri |
HTTP method, full URI | runtime |
proxy.pathsuffix, proxy.basepath |
path relative to / full base path | runtime |
response.status.code, response.content |
backend's reply | runtime |
verifyapikey.{policy}.client_id |
the validated app's key | VerifyAPIKey |
developer.email, apiproduct.name |
app metadata | VerifyAPIKey/OAuthV2 |
ratelimit.{policy}.allowed.count / .used.count |
quota counters | Quota |
fault.name, error.status.code |
error context | fault handling |
Inside policy XML, {variable} interpolates a value:
<Value>{"app": "{developer.email}"}</Value>.
Discover variables in Trace
The Trace tool shows every variable's value after each step. When a
condition doesn't fire, compare the actual variable values against your
<Condition> — it's almost always a pathsuffix or verb mismatch.
Fault handling¶
Any policy can fail → the flow short-circuits into FaultRules (on the
same endpoint), then DefaultFaultRule if nothing matches. Faults carry
fault.name (e.g. FailedToResolveAPIKey) you match on:
<FaultRules>
<FaultRule name="bad-key">
<Step><Name>AM-Error-401</Name></Step>
<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>
</FaultRules>
<DefaultFaultRule name="default-fault">
<Step><Name>AM-Error-Generic</Name></Step>
</DefaultFaultRule>
Lab 6 exercises this deliberately — you'll break the key check on purpose and watch the fault pipeline produce a clean JSON error.
Fault facts that bite
- FaultRules are evaluated top to bottom, first match wins; the
DefaultFaultRuleruns only if none did (unlessAlwaysEnforce). - The normal PostFlow is skipped on a fault — decorate error responses (e.g. CORS headers) inside the fault policies.
- A step with
continueOnError="true"that fails does not trigger fault handling — useful for optional enrichment, dangerous for security. - FaultRules can live on the TargetEndpoint too; those catch backend
errors (e.g.
ErrorResponseCodefor a 5xx from the target) before the proxy-level rules see them.
Predict before you read on
With the excerpt above, a client sends GET /labs/orders with no API
key. Which steps run? Is JS-ShapeResponse among them? Does the
PostFlow run?
Answer
VerifyAPIKey-Check runs and faults. Quota, the conditional flow
and JS never execute. The PostFlow is skipped as well — the request
jumps straight to fault handling. See the next section.
Revision model¶
Every deploy creates a new numbered revision; traffic moves to it
atomically. --ovr in deploy.sh redeploys in place — fine for labs. In
production you promote a fixed revision through environments
(see Deploy & CI/CD).
Check yourself¶
1. Which file would you open to change the backend URL? Which to change the public path?
targets/default.xml (<URL>) for the backend; proxies/default.xml
(<BasePath>) for the public path.
2. Two conditional flows both match a request. Which runs?
Only the first in document order. PreFlow and PostFlow still run.
3. On the response side, which runs first: the proxy's PreFlow or the target's PreFlow?
The target's. The response retraces the path: target phases, then proxy phases.
4. You rename a policy's name attribute but not the <Step>. What happens at import?
The import fails (or the step can't resolve a policy): step name, file
name and name attribute must all agree.
5. Why is the PostFlow a poor place to enforce a security check?
It runs after the target was already called, and it is skipped on faults. Security belongs in the PreFlow (or an early conditional flow).
Ready for the full picture? Walk the real bundle in Bundle Walkthrough, then start Lab 1.