Policies are where Apigee earns its keep. They're declarative, ordered steps you attach to flows. This page covers the essential categories and the anti-patterns that quietly wreck performance.
Policy categories
Security: VerifyAPIKey, OAuthV2, VerifyJWT/GenerateJWT, BasicAuthentication, SAML. Traffic management: Quota, SpikeArrest, ConcurrentRateLimit, ResponseCache. Mediation: AssignMessage, ExtractVariables, JSONToXML/XMLToJSON, JSONThreatProtection. Extension: ServiceCallout, JavaScript, Java, Python, MessageLogging, Flow Callout (shared flows).
Security essentials
API keys — simplest consumer identity:
<VerifyAPIKey name="VerifyAPIKey">
<APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>OAuth 2.0 / JWT — for proper authorization. Verify a bearer token in PreFlow:
<OAuthV2 name="VerifyAccessToken">
<Operation>VerifyAccessToken</Operation>
</OAuthV2>Validate JWTs (issuer, audience, signature via JWKS) with VerifyJWT for token-based, zero-shared-secret auth.
Traffic management
- SpikeArrest — smooths bursts (protects backends from sudden load). Set just above expected peak rate.
- Quota — enforces business limits per app/developer (e.g. 10k/day). Distinct from SpikeArrest (abuse protection vs. plan enforcement) — use both.
- ResponseCache — cache backend responses to cut latency and load.
<SpikeArrest name="SpikeArrest"><Rate>30ps</Rate></SpikeArrest>
<Quota name="QuotaPerApp"><Allow count="10000"/><Interval>1</Interval><TimeUnit>day</TimeUnit></Quota>Mediation
Transform between client and backend shapes without changing either: AssignMessage (build/modify messages, set headers), ExtractVariables (pull values from payloads), JSONToXML/XMLToJSON. Add JSONThreatProtection to reject malicious payloads (deep nesting, huge arrays).
Reuse with Shared Flows
Factor common logic (auth + quota + logging) into a Shared Flow and attach via FlowCallout or a Flow Hook so every proxy enforces the same baseline — DRY governance.
Anti-patterns (important)
- ❌ JavaScript ServiceCallout to invoke backends. Don't make HTTP calls from a JS policy. Use the ServiceCallout policy (or proper target/route rules) — JS callouts are slow, hard to debug, swallow errors, and don't get gateway-level connection management. Use JS only for light variable manipulation, never for I/O.
- ❌ Heavy logic in JavaScript/Java policies. Prefer native policies (AssignMessage, ExtractVariables) — they're faster and observable in Trace. Reach for code only when no policy fits.
- ❌ Synchronous MessageLogging to a slow endpoint in the request path — log asynchronously.
- ❌ No SpikeArrest/Quota — unprotected backends.
- ❌ Secrets in policy XML — use the encrypted KVM (Key Value Map) or GCP Secret Manager.
- ❌ Giant PreFlow with order-dependent steps no one understands — modularise with shared flows.
Best practices
- ✅ Fail fast: security + threat protection + spike arrest early in PreFlow.
- ✅ Native policies over custom code; JS for glue only.
- ✅ Centralise cross-cutting logic in shared flows.
- ✅ Store secrets/config in encrypted KVMs per environment.
Next: organise environments and deploy safely → Environments & Deployment →