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:

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

Caching

Security

Mediation

Integration & Extension

Validation

AI/LLM

Reference Documentation

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