apigee-x-proxy-development

Apigee X API Proxy Development

Comprehensive skill for building API proxies on Google Cloud's Apigee X platform. Covers the full proxy development lifecycle: bundle structure, endpoint configuration, flow design, policy implementation, fault handling, JavaScript extensibility, shared flows, and advanced patterns.

This skill covers: API proxy bundle authoring, policy configuration (42+ policy types), flow execution design, conditional routing, fault handling, JavaScript callouts, shared flows, and advanced development patterns.

This skill does NOT cover: Apigee X deployment/provisioning, CI/CD pipelines, Apigee Hybrid-specific configuration, GCP infrastructure setup, or Apigee management API usage. Focus is exclusively on proxy development artifacts.

When to Use This Skill

Use this skill when the user is:

• Building new API proxy bundles from scratch
• Writing or configuring Apigee policies (security, mediation, traffic management, etc.)
• Designing flow pipelines (PreFlow, conditional flows, PostFlow, PostClientFlow)
• Configuring ProxyEndpoints, TargetEndpoints, or RouteRules
• Implementing fault handling (FaultRules, DefaultFaultRule, RaiseFault)
• Writing JavaScript callout code for Apigee proxies
• Creating or consuming shared flows
• Debugging proxy execution or policy errors
• Reviewing existing proxy configurations for correctness or best practices
• Asking about Apigee X policy behavior, flow variables, or conditions

Do NOT use this skill when the user is:

• Deploying proxies to Apigee environments (use deployment tooling instead)
• Configuring Apigee Hybrid runtime infrastructure
• Setting up CI/CD for proxy bundles
• Managing Apigee organizations, environments, or environment groups via API
• Working with non-Apigee API gateways

Consulting Official Documentation

When you need to look up specific policy syntax, verify behavior, or find recent changes:

• Web search: Use site:cloud.google.com/apigee to restrict results to official Apigee X docs
• Policy reference: Fetch https://cloud.google.com/apigee/docs/api-platform/reference/policies/[policy-name]-policy
• Configuration reference: Fetch https://cloud.google.com/apigee/docs/api-platform/reference/api-proxy-configuration-reference
• Flow variables: Fetch https://cloud.google.com/apigee/docs/api-platform/reference/variables-reference
• Conditions: Fetch https://cloud.google.com/apigee/docs/api-platform/reference/conditions-reference
• Vetted examples: Browse https://github.com/GoogleCloudPlatform/apigee-samples for production patterns

Important: Do NOT use docs.apigee.com — that is legacy Apigee Edge documentation. Always use cloud.google.com/apigee for Apigee X.

API Proxy Bundle Quick Reference

apiproxy/
├── MyProxy.xml                    # Root proxy definition (name + revision)
├── proxies/                       # ProxyEndpoint definitions
│   └── default.xml
├── targets/                       # TargetEndpoint definitions
│   └── default.xml
├── policies/                      # All policy XML files
│   ├── AM-SetHeaders.xml
│   ├── EV-ExtractPath.xml
│   └── ...
└── resources/                     # Custom code and resources
    ├── jsc/                       # JavaScript files
    ├── java/                      # Java JAR files
    └── xsl/                       # XSLT transformations

Policy Naming Conventions

Follow the [Abbreviation]-[Purpose].xml pattern from GoogleCloudPlatform/apigee-samples:

Abbreviation	Policy Type	Example
AM	AssignMessage	AM-SetHeaders.xml
EV	ExtractVariables	EV-ExtractUserId.xml
SC	ServiceCallout	SC-CallBackend.xml
RF	RaiseFault	RF-InvalidInput.xml
FC	FlowCallout	FC-AuthSharedFlow.xml
SA	SpikeArrest	SA-ProtectBackend.xml
Q	Quota	Q-DailyLimit.xml
RC	ResponseCache	RC-CacheResponse.xml
LC	LookupCache	LC-GetCachedValue.xml
PC	PopulateCache	PC-StoreValue.xml
IC	InvalidateCache	IC-ClearCache.xml
KVM	KeyValueMapOperations	KVM-GetConfig.xml
JS	JavaScript	JS-TransformResponse.xml
JWT	JWT policies	JWT-GenerateToken.xml
OAuth	OAuthV2	OAuth-VerifyToken.xml
VAK	VerifyAPIKey	VAK-CheckKey.xml
ML	MessageLogging	ML-LogToCloud.xml
DC	DataCapture	DC-CaptureMetrics.xml
CORS	CORS	CORS-AllowOrigins.xml
JTP	JSONThreatProtection	JTP-ValidatePayload.xml
XTP	XMLThreatProtection	XTP-ValidateXML.xml
OAS	OASValidation	OAS-ValidateRequest.xml

See proxy_bundle_anatomy.md for full details.

Development Workflow

Phase 1: Define Proxy Structure

1. Create the apiproxy/ directory with root XML, proxies/, targets/, policies/
2. Configure ProxyEndpoint: set BasePath, define HTTPProxyConnection
3. Configure TargetEndpoint: set backend URL or LoadBalancer
4. Set up RouteRules to connect proxy to target

Reference: proxy_bundle_anatomy.md, endpoints_and_routing.md

Phase 2: Design Flow Pipeline

1. Map API operations to conditional flows using verb + path conditions
2. Place security policies in PreFlow (execute for every request)
3. Place business logic in conditional flows (execute per operation)
4. Place response headers and caching in PostFlow
5. Place MessageLogging in PostClientFlow (guarantees execution even on fault — PostFlow is skipped if proxy errors before reaching it)

Reference: flows_and_execution.md, flow_variables_and_conditions.md

Phase 3: Implement Policies

Follow this ordering within flows — security first, then mediation, then traffic:

1. Security: VerifyAPIKey, OAuthV2, VerifyJWT, AccessControl, threat protection
2. Mediation: ExtractVariables, AssignMessage, transformations
3. Traffic management: SpikeArrest, Quota
4. Caching: ResponseCache (typically in PostFlow response)
5. Logging: MessageLogging (typically in PostClientFlow)

Reference: policies_security.md, policies_mediation.md, policies_traffic_management.md, policies_caching.md, policies_integration.md

Phase 4: Add Fault Handling

1. Define FaultRules for known error types (auth failures, quota exceeded, backend errors)
2. Add DefaultFaultRule as catch-all with consistent error format
3. Use RaiseFault for custom validation errors
4. Set continueOnError only for policies where failure is acceptable

Reference: fault_handling.md

Phase 5: Optimize and Extend

1. Extract reusable policy sequences into shared flows
2. Add response caching where appropriate
3. Consider advanced patterns: proxy chaining, composite APIs, circuit breakers
4. Add JavaScript callouts for complex transformations only when policies don't suffice

Reference: shared_flows.md, javascript_development.md, advanced_patterns.md, anti_patterns_and_best_practices.md

Flow Execution Model

CLIENT REQUEST
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
│                                                 │
│  RouteRule evaluation → select TargetEndpoint   │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌────────────────┐  ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional    │→ │PostFlow │ │
│  │ (Request)│  │ Flows (Request)│  │(Request)│ │
│  └──────────┘  └────────────────┘  └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
  BACKEND SERVICE (request sent, response received)
     │
     ▼
┌─────────────────────────────────────────────────┐
│  TARGET ENDPOINT                                │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PROXY ENDPOINT                                 │
│  ┌──────────┐  ┌─────────────────┐ ┌─────────┐ │
│  │ PreFlow  │→ │ Conditional     │→│PostFlow │ │
│  │(Response)│  │ Flows (Response)│ │(Response│ │
│  └──────────┘  └─────────────────┘ └─────────┘ │
└─────────────────────────────────────────────────┘
     │
     ▼
CLIENT RESPONSE SENT
     │
     ▼
┌─────────────────────────────────────────────────┐
│  PostClientFlow (async — after response sent)   │
│  Only: MessageLogging, FlowCallout              │
└─────────────────────────────────────────────────┘

Key rules:

• Conditional flows: Only the FIRST flow whose condition evaluates to true executes. Order matters.
• PostClientFlow: Executes even if the proxy errored. Only MessageLogging and FlowCallout policies allowed.
• FaultRules: Execute when a policy raises a fault. Skip remaining flow steps and enter error flow.

Policy Catalog

Traffic Management

Policy	Purpose	Reference
SpikeArrest	Throttle request rate to protect backends	policies_traffic_management.md
Quota	Enforce consumption limits over time periods	policies_traffic_management.md
ResetQuota	Dynamically adjust quota counters mid-cycle	policies_traffic_management.md

Caching

Policy	Purpose	Reference
ResponseCache	Cache backend responses by request attributes	policies_caching.md
LookupCache	Retrieve values from general-purpose cache	policies_caching.md
PopulateCache	Store values in general-purpose cache	policies_caching.md
InvalidateCache	Remove entries from cache	policies_caching.md

Security

Policy	Purpose	Reference
VerifyAPIKey	Validate API key from header or query param	policies_security.md
BasicAuthentication	Encode/decode Base64 Basic auth credentials	policies_security.md
OAuthV2	Generate/verify OAuth 2.0 tokens	policies_security.md
GenerateJWT	Create signed or encrypted JWT tokens	policies_security.md
VerifyJWT	Validate JWT signatures and claims	policies_security.md
DecodeJWT	Decode JWT without signature verification	policies_security.md
HMAC	Compute/verify hash-based message auth codes	policies_security.md
CORS	Enable cross-origin resource sharing	policies_security.md
AccessControl	IP-based allow/deny rules	policies_security.md
VerifyIAM	Google Cloud IAM-based authorization	policies_security.md
JSONThreatProtection	Protect against malicious JSON payloads	policies_security.md
XMLThreatProtection	Protect against malicious XML payloads	policies_security.md

Mediation

Policy	Purpose	Reference
AssignMessage	Modify/create request or response messages	policies_mediation.md
ExtractVariables	Extract content from messages into variables	policies_mediation.md
HTTPModifier	Add/remove/set HTTP headers and params	policies_mediation.md
XMLtoJSON	Convert XML payloads to JSON	policies_mediation.md
JSONtoXML	Convert JSON payloads to XML	policies_mediation.md
JavaScript	Execute custom JavaScript code	javascript_development.md

Integration & Extension

Policy	Purpose	Reference
ServiceCallout	Call external REST services during flow	policies_integration.md
FlowCallout	Invoke a shared flow	policies_integration.md
ExternalCallout	Send gRPC requests to external servers	policies_integration.md
KeyValueMapOperations	Read/write key-value map entries	policies_integration.md
ReadPropertySet	Read property set values into variables	policies_integration.md
AccessEntity	Look up entity profiles at runtime	policies_integration.md
RaiseFault	Generate custom fault responses	fault_handling.md
AssertCondition	Evaluate conditional statements	policies_integration.md
MessageLogging	Log to Cloud Logging or syslog	policies_integration.md
PublishMessage	Publish to Pub/Sub topics	policies_integration.md
DataCapture	Capture custom analytics data into Data Collectors	policies_integration.md

Validation

Policy	Purpose	Reference
OASValidation	Validate against OpenAPI 3.0 specs	policies_security.md
GraphQL	Parse and validate GraphQL payloads	policies_security.md

AI/LLM

Policy	Purpose	Reference
LLMTokenQuota	Enforce token consumption limits	advanced_patterns.md
PromptTokenLimit	Throttle token consumption per request	advanced_patterns.md
SanitizeUserPrompt	Filter harmful content from prompts	advanced_patterns.md
SanitizeModelResponse	Filter harmful content from LLM responses	advanced_patterns.md
SemanticCacheLookup	Semantic similarity cache lookup	advanced_patterns.md
SemanticCachePopulate	Cache responses by semantic similarity	advanced_patterns.md

Reference Documentation

Document	Description
proxy_bundle_anatomy.md	Bundle directory structure, file types, naming conventions
endpoints_and_routing.md	ProxyEndpoint, TargetEndpoint, RouteRules, proxy chaining
flows_and_execution.md	Flow pipeline, PreFlow/PostFlow/conditional flows, execution order
flow_variables_and_conditions.md	Variable system, conditions syntax, message templates
policies_traffic_management.md	SpikeArrest, Quota, ResetQuota
policies_caching.md	ResponseCache, cache-aside pattern, PopulateCache, LookupCache, InvalidateCache
policies_security.md	API keys, OAuth 2.0, JWT, CORS, threat protection, IAM
policies_mediation.md	AssignMessage, ExtractVariables, JSON/XML transforms
policies_integration.md	ServiceCallout, FlowCallout, KVM deep dive, PropertySets, logging, RaiseFault
load_balancing_and_routing.md	Target servers, load balancing algorithms, health monitors, advanced routing
fault_handling.md	FaultRules, DefaultFaultRule, error flows, error responses
javascript_development.md	JavaScript object model, patterns, best practices
shared_flows.md	Creating and consuming shared flows, flow hooks
advanced_patterns.md	Proxy chaining, composite APIs, circuit breaker, AI/LLM
anti_patterns_and_best_practices.md	Common mistakes, production best practices
debugging_and_performance.md	Debug sessions, trace methodology, performance optimization
multi_tenant_patterns.md	Multi-tenant routing, isolation, per-tenant config and rate limiting
websockets_and_streaming.md	WebSocket proxying, SSE, HTTP streaming, timeout gotchas
end_to_end_examples.md	4 complete proxy bundle walkthroughs

Quick Start: Minimal Proxy Bundle

apiproxy/MinimalProxy.xml

<?xml version="1.0" encoding="UTF-8"?>
<APIProxy name="MinimalProxy" revision="1">
  <DisplayName>Minimal Proxy</DisplayName>
  <Description>Simple passthrough proxy</Description>
</APIProxy>

apiproxy/proxies/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<ProxyEndpoint name="default">
  <HTTPProxyConnection>
    <BasePath>/v1/minimal</BasePath>
  </HTTPProxyConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>

  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

apiproxy/targets/default.xml

<?xml version="1.0" encoding="UTF-8"?>
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <URL>https://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>

  <PreFlow name="PreFlow">
    <Request/>
    <Response/>
  </PreFlow>

  <Flows/>

  <PostFlow name="PostFlow">
    <Request/>
    <Response/>
  </PostFlow>
</TargetEndpoint>

Common Development Recipes

Add API Key Protection

Add VerifyAPIKey to PreFlow — all requests must include a valid key:

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Name>VAK-VerifyKey</Name>
    </Step>
  </Request>
</PreFlow>

See policies_security.md for VerifyAPIKey policy XML.

Add OAuth 2.0

Create a token endpoint flow + verify tokens on resource flows:

<Flow name="token">
  <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
  <Request>
    <Step><Name>OAuth-GenerateToken</Name></Step>
  </Request>
</Flow>
<Flow name="protected-resource">
  <Condition>proxy.pathsuffix MatchesPath "/resource"</Condition>
  <Request>
    <Step><Name>OAuth-VerifyToken</Name></Step>
  </Request>
</Flow>

See policies_security.md for OAuthV2 policy configuration.

Add Rate Limiting

Combine SpikeArrest (protection) with Quota (SLA enforcement):

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>SA-ProtectBackend</Name></Step>
    <Step><Name>Q-DailyLimit</Name></Step>
  </Request>
</PreFlow>

See policies_traffic_management.md.

Add Response Caching

Place ResponseCache in the flow — it handles both lookup and population:

<PostFlow name="PostFlow">
  <Response>
    <Step><Name>RC-CacheResponse</Name></Step>
  </Response>
</PostFlow>

See policies_caching.md.

Add CORS

Attach CORS policy in PreFlow to handle preflight and response headers:

<PreFlow name="PreFlow">
  <Request>
    <Step><Name>CORS-AllowOrigins</Name></Step>
  </Request>
</PreFlow>

See policies_security.md for CORS policy XML.

Call an External Service

Use ServiceCallout to call external APIs during request processing:

<Flow name="enrich-request">
  <Request>
    <Step><Name>SC-GetUserProfile</Name></Step>
    <Step><Name>EV-ExtractProfile</Name></Step>
  </Request>
</Flow>

See policies_integration.md.

Build Consistent Error Responses

Add FaultRules + DefaultFaultRule to ProxyEndpoint:

<FaultRules>
  <FaultRule name="auth-error">
    <Condition>fault.name = "FailedToResolveAPIKey"</Condition>
    <Step><Name>AM-AuthError</Name></Step>
  </FaultRule>
</FaultRules>
<DefaultFaultRule>
  <AlwaysEnforce>true</AlwaysEnforce>
  <Step><Name>AM-GenericError</Name></Step>
</DefaultFaultRule>

See fault_handling.md.

Create and Use a Shared Flow

Extract reusable logic into a shared flow, invoke via FlowCallout:

<!-- In consuming proxy -->
<PreFlow name="PreFlow">
  <Request>
    <Step><Name>FC-AuthSharedFlow</Name></Step>
  </Request>
</PreFlow>

See shared_flows.md.

Best Practices Summary

• Policy ordering: Security (PreFlow) → Mediation → Traffic management → Caching (PostFlow) → Logging (PostClientFlow)
• Naming: Always use [Abbreviation]-[Purpose].xml for policy files
• Policies over code: Use built-in policies first; only use JavaScript for logic that policies cannot express
• Fault handling: Every proxy should have a DefaultFaultRule with a consistent error response format
• Shared flows: Extract any policy sequence used in 2+ proxies into a shared flow
• Base paths: Use versioned paths (/v1/resource) and ensure uniqueness per environment
• Conditions: Place the most specific conditional flows first (first match wins)
• PostClientFlow: Always use for MessageLogging to guarantee execution regardless of errors
• Caching: Set ExcludeErrorResponse to true on ResponseCache to avoid caching error responses
• Large payloads: Minimize policies that parse large payloads; enable streaming for passthrough scenarios
• Anti-patterns: See anti_patterns_and_best_practices.md for the complete catalog