Policy Cookbook¶
Copy-paste templates for the policies you'll reach for most. File names
follow the XX-Purpose.xml convention — the <Step><Name> must match the
file's <name> attribute.
Every policy is a file
Save each block under apiproxy/policies/<Name>.xml, then attach with
<Step><Name><Name></Name></Step> in the flow where it should run.
How to read a policy
Every recipe below has the same skeleton — see
Core Concepts → Anatomy of one policy file.
Ask three questions of each: what does it need (variables in),
what does it produce (variables/message out), and how does it fail
(fault.name).
Security¶
Sets verifyapikey.VA-Check.client_id, developer.email,
apiproduct.name. Faults: FailedToResolveAPIKey, InvalidApiKey,
InvalidApiKeyForGivenResource.
Reads Authorization: Bearer <token>. Sets accesstoken.client_id,
accesstoken.scope, apiproduct.name.
<VerifyJWT name="VJ-Check">
<Algorithm>RS256</Algorithm>
<Source>request.header.authorization</Source>
<PublicKey>
<JWKS uri="https://idp.example.com/.well-known/jwks.json"/>
</PublicKey>
<Issuer>https://idp.example.com</Issuer>
<Audience>my-api</Audience>
</VerifyJWT>
Claims land in jwt.VJ-Check.decoded.claim.* and
jwt.VJ-Check.claim.*.
<BasicAuthentication name="BA-Check">
<Operation>Decode</Operation>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<User ref="request.header.username"/>
<Password ref="request.header.password"/>
<AssignTo createNew="false">request.authorization</AssignTo>
<Source>request.header.authorization</Source>
</BasicAuthentication>
Decode only — pair with a ServiceCallout or AccessEntity to actually
validate. TLS is non-negotiable: Basic Auth sends credentials
effectively in plaintext.
Traffic management¶
Mediation¶
<AssignMessage name="AM-Munge">
<Copy>
<Headers><Header name="x-tenant"/></Headers>
</Copy>
<Add>
<Headers><Header name="x-gateway">apigee</Header></Headers>
</Add>
<Remove>
<QueryParams><QueryParam name="apikey"/></QueryParams>
</Remove>
<AssignTo createNew="false">request</AssignTo>
</AssignMessage>
Resilience & operations¶
<ResponseCache name="RC">
<CacheKey>
<Prefix/>
<KeyFragment ref="proxy.pathsuffix"/>
</CacheKey>
<ExpirySettings><TimeoutInSec>300</TimeoutInSec></ExpirySettings>
<SkipCacheLookup>request.header.x-no-cache Exists</SkipCacheLookup>
<SkipCachePopulation>response.status.code != 200</SkipCachePopulation>
</ResponseCache>
<StatisticsCollector name="SC-Stats">
<Statistics>
<Statistic name="order_value" ref="response.header.x-order-total" type="double">0</Statistic>
</Statistics>
</StatisticsCollector>
Feeds custom analytics dimensions in Apigee's reports.
<JSONThreatProtection name="JTP-Check">
<ArrayElementCount>20</ArrayElementCount>
<ContainerDepth>5</ContainerDepth>
<StringValueLength>500</StringValueLength>
<Source>request</Source>
</JSONThreatProtection>
Rejects oversized/deeply-nested bodies before they're parsed. More in Advanced Topics.
Fault names worth a FaultRule¶
fault.name |
Raised by | Typical status |
|---|---|---|
FailedToResolveAPIKey, InvalidApiKey |
VerifyAPIKey | 401 |
InvalidAccessToken |
OAuthV2 Verify | 401 |
InvalidSignature, TokenExpired |
VerifyJWT | 401 |
QuotaViolation, SpikeArrestViolation |
Quota, SpikeArrest | 429 |
RaiseFault (your own) |
RaiseFault | whatever you set |
ExecutionFailed |
ServiceCallout, JavaScript | 500/502 |
InsufficientKeyLength |
GenerateJWT / VerifyJWT (HS key < 32 bytes) | 401 |
ErrorResponseCode |
TargetEndpoint, when the backend returns a non-success code | backend's code |