API / APIGEE Gateway Interview Questions

<!-- Simplified proxy structure -->
apigee-proxy/
  apiproxy/
    my-proxy.xml          <!-- root proxy descriptor -->
    proxies/
      default.xml          <!-- ProxyEndpoint definition -->
    targets/
      default.xml          <!-- TargetEndpoint definition -->
    policies/
      VerifyAPIKey.xml
      Quota.xml
      AssignMessage.xml
    resources/
      jsc/
        transform.js

<!-- Example: PreFlow with security policy -->
<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step><Name>VerifyAPIKey</Name></Step>   <!-- Step 1: check key -->
      <Step><Name>Quota</Name></Step>           <!-- Step 2: enforce quota -->
    </Request>
    <Response/>
  </PreFlow>
  <Flows>
    <Flow name="GetOrders">
      <Condition>request.verb == "GET" and proxy.pathsuffix MatchesPath "/orders"</Condition>
      <Request>
        <Step><Name>AssignMessage.SetHeaders</Name></Step>
      </Request>
    </Flow>
  </Flows>
  <PostFlow name="PostFlow">
    <Response>
      <Step><Name>ResponseCache</Name></Step>  <!-- cache the response -->
    </Response>
  </PostFlow>
</ProxyEndpoint>

<!-- VerifyAPIKey policy example -->
<VerifyAPIKey name="VerifyAPIKey">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

<!-- Quota policy example -->
<Quota name="Quota" type="rollingwindow">
  <Interval>1</Interval>
  <TimeUnit>minute</TimeUnit>
  <Allow count="100"/>
</Quota>

<!-- AssignMessage policy example -->
<AssignMessage name="AM.SetBackendHeaders">
  <AssignTo createNew="false" type="request"/>
  <Set>
    <Headers>
      <Header name="x-internal-caller">apigee</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

<!-- Policy definition -->
<VerifyAPIKey name="VerifyAPIKey">
  <!-- Read the key from the x-api-key request header -->
  <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

<!-- Alternative: read from query parameter -->
<VerifyAPIKey name="VerifyAPIKey-QP">
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

<!-- Placement: always in ProxyEndpoint PreFlow so every request is checked -->
<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <Step><Name>VerifyAPIKey</Name></Step>  <!-- Must run first -->
    </Request>
  </PreFlow>
</ProxyEndpoint>

<!-- After verification, Apigee populates flow variables:
  verifyapikey.VerifyAPIKey.client_id       -- the app consumer key
  verifyapikey.VerifyAPIKey.developer.email
  verifyapikey.VerifyAPIKey.app.name
  verifyapikey.VerifyAPIKey.api_product.name -->

<!-- Step 1: GenerateAccessToken policy (Apigee acts as auth server) -->
<OAuthV2 name="GenerateToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>  <!-- 1 hour in milliseconds -->
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

<!-- Step 2: VerifyAccessToken policy (protect API proxies) -->
<OAuthV2 name="VerifyToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

<!-- Client credentials token request:
POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Response:
{
  "access_token": "eyJ...",
  "token_type": "BearerToken",
  "expires_in": "3599"
} -->

<!-- Quota policy: business entitlement -->
<Quota name="Quota" type="rollingwindow">
  <Allow count="1000"/>       <!-- 1000 calls... -->
  <Interval>1</Interval>
  <TimeUnit>day</TimeUnit>    <!-- ...per day -->
  <Identifier ref="verifyapikey.VerifyAPIKey.client_id"/>  <!-- per app -->
</Quota>

<!-- SpikeArrest policy: smooth out bursts -->
<SpikeArrest name="SpikeArrest">
  <!-- Allow max 10 requests per second
       Apigee converts to "1 req per 100ms" -->
  <Rate>10ps</Rate>   <!-- ps = per second, pm = per minute -->
</SpikeArrest>

<!-- Best practice: use BOTH
  SpikeArrest runs first to prevent sudden spikes
  Then Quota enforces the developer's entitlement -->

<!-- API Product configuration (conceptual) -->
API Product: "Premium Weather API"
  - Proxies:        weather-proxy
  - Environments:   prod
  - Resource paths: /current, /forecast, /historical
  - Quota:          10,000 calls/day
  - Approval:       automatic

API Product: "Free Weather API"
  - Proxies:        weather-proxy
  - Environments:   prod
  - Resource paths: /current  (forecast and historical NOT included)
  - Quota:          100 calls/day
  - Approval:       automatic

# Same proxy, different products = different entitlements per tier
# Developer creates an App, subscribes to a Product,
# receives a consumer key tied to that product's quota

# Typical environment setup:
#
# Organisation: my-company
#   |-- Environment: dev      (https://dev.api.example.com)
#   |-- Environment: test     (https://test.api.example.com)
#   |-- Environment: prod     (https://api.example.com)
#
# Proxy deployed to both test and prod:
# gcloud apigee deployments create \
#   --organization=my-company \
#   --environment=prod \
#   --api=orders-proxy \
#   --revision=3

# Environment-specific configuration:
# - Target URLs different per environment (dev points to dev backend)
# - Quotas may differ between test and prod
# - Different SSL certificates per environment
# - KVM (Key Value Maps) scoped per environment for config values

<!-- In an API proxy: calling a shared flow -->
<FlowCallout name="FC.CommonSecurity">
  <SharedFlowBundle>common-security</SharedFlowBundle>
</FlowCallout>

<!-- common-security shared flow content (sharedflowbundle/): -->
<!--   VerifyAPIKey.xml       -->
<!--   SpikeArrest.xml        -->
<!--   Quota.xml              -->
<!--   MessageLogging.xml     -->

<!-- Typical shared flow use cases:
  - Common security (VerifyAPIKey + Quota + SpikeArrest)
  - Standard error handling (FaultRules + AssignMessage)
  - Logging (MessageLogging + StatisticsCollector)
  - Header injection (add internal headers before backend)
  - CORS handling across all proxies
-->

<!-- A platform team creates and governs the shared flow.
     Individual API teams attach it via FlowCallout.
     Policy change in one place = change across all proxies. -->

<!-- ResponseCache policy -->
<ResponseCache name="ResponseCache">
  <!-- How to build the cache key -->
  <CacheKey>
    <Prefix>weather</Prefix>
    <!-- Cache key includes the city query parameter -->
    <KeyFragment ref="request.queryparam.city" />
  </CacheKey>
  <!-- How long to cache the response -->
  <ExpirySettings>
    <TimeoutInSec>300</TimeoutInSec>  <!-- 5 minutes -->
  </ExpirySettings>
  <!-- Skip caching if the client sends Cache-Control: no-cache -->
  <SkipCacheLookup>request.header.cache-control = "no-cache"</SkipCacheLookup>
</ResponseCache>

<!-- Placement: ResponseCache appears in BOTH:
  1. ProxyEndpoint PreFlow Request   (to check for cache hit)
  2. ProxyEndpoint PostFlow Response (to populate the cache on cache miss)
  Apigee handles the dual role automatically with this single policy -->

<!-- Flow variables after policy executes:
  responsecache.ResponseCache.cachehit    -- true/false
  responsecache.ResponseCache.cachekey    -- the computed cache key -->

<!-- Set headers on the outgoing request to backend -->
<AssignMessage name="AM.SetBackendHeaders">
  <AssignTo createNew="false" type="request"/>
  <Set>
    <Headers>
      <Header name="x-internal-caller">apigee-proxy</Header>
      <Header name="x-correlation-id">{request.header.x-correlation-id}</Header>
    </Headers>
  </Set>
  <Remove>
    <Headers>
      <Header name="x-api-key"/>  <!-- strip the key before forwarding -->
    </Headers>
  </Remove>
</AssignMessage>

<!-- Create a custom error response -->
<AssignMessage name="AM.CustomError">
  <AssignTo createNew="true" type="response"/>
  <Set>
    <StatusCode>403</StatusCode>
    <ReasonPhrase>Forbidden</ReasonPhrase>
    <Headers>
      <Header name="Content-Type">application/json</Header>
    </Headers>
    <Payload contentType="application/json">{
      "error": "access_denied",
      "message": "You do not have permission to call this API."
    }</Payload>
  </Set>
</AssignMessage>

<!-- Change the request verb and path -->
<AssignMessage name="AM.RewritePath">
  <AssignTo createNew="false" type="request"/>
  <Set>
    <Verb>POST</Verb>
    <Path>/v2/orders</Path>
  </Set>
</AssignMessage>

<!-- Extract from JSON request body -->
<ExtractVariables name="EV.ExtractBody">
  <Source>request</Source>
  <JSONPayload>
    <Variable name="orderId">
      <JSONPath>$.order.id</JSONPath>
    </Variable>
    <Variable name="customerId">
      <JSONPath>$.order.customer.id</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<!-- Extract from URI path pattern: /orders/{orderId}/items/{itemId} -->
<ExtractVariables name="EV.PathVars">
  <Source>request</Source>
  <URIPath>
    <Pattern ignoreCase="true">/orders/{orderId}/items/{itemId}</Pattern>
  </URIPath>
</ExtractVariables>

<!-- Extract from query parameter -->
<ExtractVariables name="EV.QueryParam">
  <Source>request</Source>
  <QueryParam name="customerId">
    <Pattern>{customerId}</Pattern>
  </QueryParam>
</ExtractVariables>

<!-- Now use the variable in a condition or another policy -->
<!-- Example: add the orderId as a backend header -->
<AssignMessage name="AM.InjectOrderId">
  <Set>
    <Headers>
      <Header name="x-order-id">{orderId}</Header>
    </Headers>
  </Set>
</AssignMessage>

<!-- ServiceCallout: call an identity service to enrich the request -->
<ServiceCallout name="SC.GetUserProfile">
  <Request variable="userProfileRequest">
    <Set>
      <Headers>
        <Header name="Authorization">Bearer {request.header.authorization}</Header>
      </Headers>
    </Set>
  </Request>
  <Response>userProfileResponse</Response>
  <HTTPTargetConnection>
    <URL>https://identity.internal.example.com/profile/{userId}</URL>
  </HTTPTargetConnection>
</ServiceCallout>

<!-- Then extract data from the callout response -->
<ExtractVariables name="EV.ExtractProfile">
  <Source>userProfileResponse</Source>
  <JSONPayload>
    <Variable name="userRole">
      <JSONPath>$.role</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

<!-- Use the role in a condition to allow/deny access -->
<!-- Condition: userRole = "admin" -->

<!-- KeyValueMapOperations policy: GET -->
<KeyValueMapOperations name="KVM.GetConfig" mapIdentifier="backend-config">
  <Scope>environment</Scope>
  <Get assignTo="backendUrl" index="1">
    <Key><Parameter>target.url</Parameter></Key>
  </Get>
</KeyValueMapOperations>

<!-- After execution, use the retrieved value -->
<!-- {backendUrl} is now available in flow variables -->

<!-- KeyValueMapOperations policy: PUT (write a value) -->
<KeyValueMapOperations name="KVM.PutToken" mapIdentifier="token-cache">
  <Scope>environment</Scope>
  <Put override="true">
    <Key><Parameter>access_token</Parameter></Key>
    <Value ref="token_response.access_token"/>
  </Put>
</KeyValueMapOperations>

<!-- CLI: create a KVM and set values -->
# Using Apigee API:
# curl -X POST "https://apigee.googleapis.com/v1/organizations/my-org/environments/prod/keyvaluemaps" \
#   -d '{"name": "backend-config", "encrypted": true}'

# Add an entry:
# curl -X POST ".../keyvaluemaps/backend-config/entries" \
#   -d '{"name": "target.url", "value": "https://api.prod.internal.com"}'

<!-- FaultRule: handle specific policy error -->
<ProxyEndpoint name="default">
  <FaultRules>
    <!-- Handle quota exceeded specifically -->
    <FaultRule name="QuotaExceeded">
      <Condition>fault.name = "QuotaExceeded"</Condition>
      <Step><Name>AM.QuotaExceededResponse</Name></Step>
    </FaultRule>
    <!-- Handle invalid API key -->
    <FaultRule name="InvalidApiKey">
      <Condition>fault.name = "InvalidApiKey"</Condition>
      <Step><Name>AM.UnauthorisedResponse</Name></Step>
    </FaultRule>
  </FaultRules>
  <!-- Catch-all for any unhandled fault -->
  <DefaultFaultRule name="DefaultFaultRule">
    <Step><Name>AM.GenericErrorResponse</Name></Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>
</ProxyEndpoint>

<!-- Custom error response policy -->
<AssignMessage name="AM.QuotaExceededResponse">
  <AssignTo createNew="true" type="response"/>
  <Set>
    <StatusCode>429</StatusCode>
    <ReasonPhrase>Too Many Requests</ReasonPhrase>
    <Headers><Header name="Content-Type">application/json</Header></Headers>
    <Payload contentType="application/json">{
      "error": "rate_limit_exceeded",
      "message": "You have exceeded your quota.",
      "retry_after": "3600"
    }</Payload>
  </Set>
</AssignMessage>

<!-- Key fault variables:
  fault.name      -- e.g. "QuotaExceeded", "InvalidApiKey"
  fault.type      -- "policy" or "messaging"
  error.message   -- the error message string -->

<!-- TargetEndpoint using a TargetServer (recommended) -->
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <LoadBalancer>
      <!-- Reference a named Target Server instead of hardcoded URL -->
      <Server name="orders-backend-server"/>
    </LoadBalancer>
    <Path>/api/v1</Path>
  </HTTPTargetConnection>
</TargetEndpoint>

<!-- Target Server definition (set in Apigee UI/API per environment) -->
<!-- Environment: prod -->
{
  "name": "orders-backend-server",
  "host": "orders.prod.internal.example.com",
  "port": 443,
  "sSLInfo": {
    "enabled": true,
    "clientAuthEnabled": false
  },
  "isEnabled": true
}

<!-- Environment: dev -->
{
  "name": "orders-backend-server",
  "host": "orders.dev.internal.example.com",
  "port": 8080,
  "sSLInfo": { "enabled": false }
}

<!-- Load balancing across multiple target servers -->
<LoadBalancer>
  <Algorithm>RoundRobin</Algorithm>
  <Server name="orders-backend-1"/>
  <Server name="orders-backend-2"/>
  <Server name="orders-backend-3"/>
</LoadBalancer>

<!-- StatisticsCollector: capture custom business dimension -->
<StatisticsCollector name="SC.OrderMetrics">
  <Statistics>
    <!-- Capture the order total from the JSON body as a metric -->
    <Statistic name="order_total" ref="order.total" type="Float"/>
    <!-- Capture the product category as a dimension for segmentation -->
    <Statistic name="product_category" ref="product.category" type="String"/>
  </Statistics>
</StatisticsCollector>

<!-- Metrics Apigee automatically captures (no policy needed):
  - request count
  - error count and error rate
  - response time (p50, p95, p99)
  - request/response payload sizes
  - developer / app / API product names
  - response status code breakdown -->

# Developer portal workflow:
#
# 1. API producer:
#    a. Creates API Proxy
#    b. Creates API Product (bundles proxy with quota/access config)
#    c. Publishes API Product to developer portal
#    d. SmartDocs (OpenAPI) documentation auto-generated
#
# 2. App developer:
#    a. Visits developer portal
#    b. Discovers available APIs in the catalogue
#    c. Reads documentation
#    d. Registers as a developer (creates account)
#    e. Creates an App and subscribes to an API Product
#    f. Receives consumer key (API key)
#    g. Calls the API using the consumer key
#
# Apigee supports two portal types:
#   - Integrated portal: built into Apigee, hosted by Google
#   - Drupal-based portal: full CMS customisation for complex needs
#   - Custom portal: build your own using Apigee APIs

<!-- VerifyJWT: validate a JWT from the Authorization header -->
<JWT name="JWT.Verify">
  <Operation>VerifyJWT</Operation>
  <Source>request.header.authorization</Source>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <!-- Validate signature using a public key stored in KVM -->
  <PublicKey>
    <JWKS ref="kvm.jwks.endpoint"/>
    <!-- Or use a static PEM:
    <Value ref="kvm.jwt.public-key"/> -->
  </PublicKey>
  <!-- Optional claims validation -->
  <Issuer>https://auth.example.com</Issuer>
  <Audience>https://api.example.com</Audience>
  <!-- AdditionalClaims can validate custom claims -->
  <AdditionalClaims>
    <Claim name="role" type="string">admin</Claim>
  </AdditionalClaims>
</JWT>

<!-- After successful VerifyJWT, claims are available as flow variables:
  jwt.JWT.Verify.claim.sub         -- subject
  jwt.JWT.Verify.claim.email
  jwt.JWT.Verify.claim.role
  jwt.JWT.Verify.claim.exp         -- expiry epoch
  jwt.JWT.Verify.valid             -- true/false
-->

<!-- GenerateJWT: create a JWT for backend (service account flow) -->
<JWT name="JWT.Generate">
  <Operation>GenerateJWT</Operation>
  <ExpiresIn>3600</ExpiresIn>
  <Subject>apigee-proxy</Subject>
  <Issuer>https://api.example.com</Issuer>
  <SecretKey>
    <Value ref="kvm.jwt.signing-secret"/>
  </SecretKey>
</JWT>

<!-- MessageLogging to Google Cloud Logging -->
<MessageLogging name="ML.AuditLog">
  <CloudLogging>
    <LogName>projects/my-project/logs/apigee-api-access</LogName>
    <Message contentType="application/json">{
      "requestId": "{request.header.x-request-id}",
      "verb": "{request.verb}",
      "path": "{request.path}",
      "clientId": "{verifyapikey.VerifyAPIKey.client_id}",
      "statusCode": "{response.status.code}",
      "latency": "{target.elapsed.time}",
      "timestamp": "{system.timestamp}"
    }</Message>
    <Labels>
      <Label>
        <Key>environment</Key>
        <Value>{environment.name}</Value>
      </Label>
    </Labels>
  </CloudLogging>
</MessageLogging>

<!-- Key placement tip:
  MessageLogging is typically placed in the PostFlow Response
  AND in the DefaultFaultRule to capture both successful and
  error responses.
  The policy executes ASYNCHRONOUSLY by default --
  it does NOT block the response to the client. -->

<!-- Alternative: syslog (for on-prem logging systems) -->
<MessageLogging name="ML.Syslog">
  <Syslog>
    <Message>{request.verb} {request.path} - {response.status.code}</Message>
    <Host>logs.example.com</Host>
    <Port>514</Port>
    <Protocol>UDP</Protocol>
  </Syslog>
</MessageLogging>

<!-- Step 1: Handle preflight OPTIONS requests
     These must return 200 immediately without hitting the backend -->
<Flow name="OptionsPreFlight">
  <Condition>request.verb == "OPTIONS"</Condition>
  <Request>
    <Step><Name>AM.AddCorsHeaders</Name></Step>
    <Step><Name>AM.ReturnOptions</Name></Step>  <!-- returns 200, no backend call -->
  </Request>
</Flow>

<!-- Step 2: Add CORS headers to all responses -->
<PostFlow name="PostFlow">
  <Response>
    <Step><Name>AM.AddCorsHeaders</Name></Step>
  </Response>
</PostFlow>

<!-- CORS headers AssignMessage policy -->
<AssignMessage name="AM.AddCorsHeaders">
  <AssignTo createNew="false" type="response"/>
  <Set>
    <Headers>
      <Header name="Access-Control-Allow-Origin">*</Header>
      <!-- Or restrict to specific origins:
      <Header name="Access-Control-Allow-Origin">
        {request.header.origin}
      </Header> -->
      <Header name="Access-Control-Allow-Methods">GET, POST, PUT, DELETE, OPTIONS</Header>
      <Header name="Access-Control-Allow-Headers">Content-Type, Authorization, x-api-key</Header>
      <Header name="Access-Control-Max-Age">3600</Header>
    </Headers>
  </Set>
</AssignMessage>

<!-- Return 200 for OPTIONS without calling backend -->
<AssignMessage name="AM.ReturnOptions">
  <AssignTo createNew="true" type="response"/>
  <Set><StatusCode>200</StatusCode></Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

# Apigee hybrid installation summary (Kubernetes-based)

# Prerequisites:
# - GKE (or any CNCF-certified Kubernetes cluster)
# - cert-manager installed
# - Anthos Service Mesh (optional but recommended)

# Install via Apigee Operator (Helm chart):
helm install apigee-operator \
  oci://us-docker.pkg.dev/apigee-release/apigee-operators/apigee-operators \
  --namespace apigee-system

# Apply the ApigeeOrganization and ApigeeEnvironment CRDs:
kubectl apply -f apigee-org.yaml
kubectl apply -f apigee-env.yaml

# Key hybrid release (mid-2026):
# Apigee hybrid v1.14.6 (released June 16, 2026)
# Apigee instance runtime 1-17-0-apigee-9

# Create an environment group with a hostname:
gcloud apigee envgroups create prod-group \
  --hostnames="api.example.com" \
  --organization=my-org

# Attach environments to the group:
gcloud apigee envgroups attachments create \
  --envgroup=prod-group \
  --environment=prod \
  --organization=my-org

# DNS configuration:
# api.example.com  CNAME  <apigee-external-ip>.nip.io
# Or: create an A record pointing to the Apigee instance IP

# Virtual host and base path routing:
# Apigee routes requests using:
#   1. The hostname in the HTTP Host header (maps to environment group)
#   2. The base path in the request URL (maps to specific proxy)
#
# Example:
#   https://api.example.com/orders/v1/...  -> orders-proxy (base path /orders/v1)
#   https://api.example.com/products/v1/... -> products-proxy (base path /products/v1)

<!-- Southbound TLS (Apigee to backend): TargetEndpoint -->
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <SSLInfo>
      <Enabled>true</Enabled>
      <!-- Verify the backend certificate -->
      <TrustStore>ref://truststore-backend</TrustStore>
      <!-- mTLS: Apigee presents its own client certificate -->
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>ref://keystore-apigee-client</KeyStore>
      <KeyAlias>apigee-client-cert</KeyAlias>
      <!-- Optionally ignore backend cert validation (dev only!) -->
      <IgnoreValidationErrors>false</IgnoreValidationErrors>
    </SSLInfo>
    <URL>https://api.internal.example.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

<!-- Keystores and Truststores are managed as
     environment-scoped resources in Apigee:

     Keystore: holds the private key + certificate Apigee presents
     Truststore: holds trusted CA certificates Apigee uses to
                 validate backend certificates

     Created via Apigee API:
     POST /organizations/{org}/environments/{env}/keystores
     POST /organizations/{org}/environments/{env}/keystores/{ks}/aliases -->

<!-- Allow only specific IP ranges (allowlist) -->
<AccessControl name="AC.AllowInternalOnly">
  <IPRules noRuleMatchAction="DENY">  <!-- DENY if no rule matches -->
    <MatchRule action="ALLOW">
      <SourceAddress mask="24">10.100.0.0</SourceAddress>  <!-- /24 subnet -->
    </MatchRule>
    <MatchRule action="ALLOW">
      <SourceAddress mask="32">203.0.113.50</SourceAddress>  <!-- single IP -->
    </MatchRule>
  </IPRules>
</AccessControl>

<!-- Denylist specific IPs (block known bad actors) -->
<AccessControl name="AC.DenyBadActors">
  <IPRules noRuleMatchAction="ALLOW">  <!-- ALLOW if no rule matches -->
    <MatchRule action="DENY">
      <SourceAddress mask="32">192.0.2.100</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<!-- IMPORTANT: In environments with a load balancer,
     the client IP may be in X-Forwarded-For, not the direct connection.
     The ValidateBasedOn element handles this:
-->
<AccessControl name="AC.XFF">
  <ValidateBasedOn>X_FORWARDED_FOR_ALL</ValidateBasedOn>
  <IPRules noRuleMatchAction="DENY">
    <MatchRule action="ALLOW">
      <SourceAddress mask="24">10.0.0.0</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

<!-- Client sends JSON; SOAP backend expects XML -->

<!-- Step 1: Convert incoming JSON request to XML -->
<JSONToXML name="JSON2XML.Request">
  <Options>
    <RootElement>root</RootElement>
    <NullValue>NULL</NullValue>
  </Options>
  <OutputVariable>request</OutputVariable>
  <Source>request</Source>
</JSONToXML>

<!-- Step 2: Route to SOAP backend (via TargetEndpoint) -->

<!-- Step 3: Convert XML response from SOAP backend to JSON -->
<XMLToJSON name="XML2JSON.Response">
  <Options>
    <RecognizeNull>true</RecognizeNull>
    <NamespaceSeparator>_</NamespaceSeparator>
    <TextAlwaysAsProperty>false</TextAlwaysAsProperty>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

<!-- Flow placement:
  JSONToXML  -> TargetEndpoint PreFlow Request (transform before backend)
  XMLToJSON  -> TargetEndpoint PostFlow Response (transform after backend)

  Full bridge pattern:
  Client (JSON) -> [JSONToXML] -> Backend (XML/SOAP)
  Client (JSON) <- [XMLToJSON] <- Backend (XML/SOAP)
-->

<!-- GraphQL policy: validate and protect GraphQL requests -->
<GraphQL name="GQL.Validate">
  <Action>parse</Action>
  <!-- Reference the uploaded GraphQL schema -->
  <ResourceURL>graphql://schema.graphql</ResourceURL>
  <!-- Protect against deeply nested queries -->
  <MaxDepth>10</MaxDepth>
  <!-- Limit number of fields per query to prevent data scraping -->
  <MaxCount>100</MaxCount>
</GraphQL>

<!-- Supported operations:
  parse     - validates the GraphQL query syntax and schema compliance
  verify    - validates that the operation is in the schema

  The policy catches:
  - Malformed GraphQL syntax
  - Operations not in the schema
  - Queries exceeding MaxDepth (circular/deep nesting attacks)
  - Queries exceeding MaxCount (field count explosion) -->

<!-- Typical proxy structure for GraphQL:
  Client -> POST /graphql (query in body)
  ProxyEndpoint:
    PreFlow:
      - VerifyAPIKey  (or OAuthV2 VerifyToken)
      - SpikeArrest
      - GQL.Validate  <- GraphQL-specific validation
  TargetEndpoint -> GraphQL backend service

  Note: Apigee proxies GraphQL as HTTP POST -
  standard HTTP policies (auth, rate limiting) all apply normally -->

# Method 1: apigeecli (official Google CLI tool)

# Import a proxy bundle:
apigeecli apis create bundle \
  --name orders-proxy \
  --proxy-zip ./orders-proxy.zip \
  --org my-org \
  --token $(gcloud auth print-access-token)

# Deploy to an environment:
apigeecli apis deploy \
  --name orders-proxy \
  --env prod \
  --org my-org \
  --rev 3 \
  --token $(gcloud auth print-access-token)

# Method 2: Apigee Management API (REST)
curl -X POST \
  "https://apigee.googleapis.com/v1/organizations/my-org/apis?action=import&name=orders-proxy" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@orders-proxy.zip"

# Method 3: Maven plugin (in pom.xml)
# <plugin>
#   <groupId>com.apigee.edge</groupId>
#   <artifactId>apigee-edge-maven-plugin</artifactId>
#   <configuration>
#     <org>my-org</org>
#     <env>prod</env>
#   </configuration>
# </plugin>

# Typical CI/CD pipeline:
# 1. Developer pushes proxy to Git
# 2. CI lints the proxy bundle (apigeelint)
# 3. CI runs unit tests (apickli / Mocha)
# 4. CI packages and deploys to test environment
# 5. Integration tests run against test
# 6. Manual approval gate
# 7. Deploy to prod

# Grant a service account the deployer role (for CI/CD):
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:cicd-sa@my-project.iam.gserviceaccount.com" \
  --role="roles/apigee.deployer"

# Grant a developer the API creator role:
gcloud projects add-iam-policy-binding my-project \
  --member="user:dev@example.com" \
  --role="roles/apigee.apiCreator"

# Principle of least privilege:
# CI/CD pipelines should use roles/apigee.deployer only
# (deploy but not delete or modify proxy logic)
# Application developers: roles/apigee.apiCreator
# Business analysts: roles/apigee.analyticsViewer

# Service account authentication for CI/CD:
gcloud auth activate-service-account \
  --key-file=cicd-sa-key.json
TOKEN=$(gcloud auth print-access-token)
apigeecli apis deploy --token $TOKEN ...

<!-- Advanced API Security actions can be attached
     to Apigee proxy flows to act on detected threats.

     Example: deny request if Advanced API Security
     identifies it as bot traffic:

     Condition in a ConditionalFlow or FaultRule:
     apigee.bot.action = "deny"

     Alternatively, add the 'apigee-bot-protection'
     shared flow from the Apigee catalogue -->

<!-- Security report categories:
  - Anomalous traffic: unusual volume spikes
  - Bot patterns: scripted/automated request signatures
  - Credential stuffing: many failed auth attempts
  - Data scraping: systematic data extraction
  - Geographic anomalies: traffic from unexpected regions

  Available in Apigee UI:
  Analyze > Security Reports > Advanced API Security -->

# Apigee API Hub CLI (apihub CLI):
# Register an API specification:
apigeecli apihub apis create \
  --org my-org \
  --region us-central1 \
  --id orders-api \
  --display-name "Orders API" \
  --description "Manages customer orders"

# Upload an OpenAPI spec version:
apigeecli apihub apis versions create \
  --org my-org \
  --region us-central1 \
  --api-id orders-api \
  --version-id v1 \
  --spec-file ./openapi.yaml

# API Hub lifecycle stages:
# DESIGN -> BUILD -> DEPLOY -> DEPRECATE -> RETIRED

# NOTE: When you deprovision Apigee API Hub,
# it deletes all associated Apigee organisations with no instances.

<!-- TargetEndpoint with load balancing across 3 servers -->
<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <LoadBalancer>
      <Algorithm>RoundRobin</Algorithm>  <!-- or: LeastConnections, Weighted, Random -->
      <Server name="backend-1"/>
      <Server name="backend-2"/>
      <Server name="backend-3">
        <Weight>2</Weight>  <!-- Receives 2x the traffic (Weighted algorithm) -->
      </Server>
      <!-- Health check / retry configuration -->
      <MaxFailures>5</MaxFailures>
      <RetryEnabled>true</RetryEnabled>
      <IsFallback>false</IsFallback>
    </LoadBalancer>
    <Path>/api/v1</Path>
  </HTTPTargetConnection>
  <!-- Active health checks (HealthMonitor) -->
  <HealthMonitor>
    <IsEnabled>true</IsEnabled>
    <IntervalInSec>5</IntervalInSec>
    <HTTPMonitor>
      <Request>
        <ConnectTimeoutInSec>2</ConnectTimeoutInSec>
        <SocketReadTimeoutInSec>2</SocketReadTimeoutInSec>
        <Verb>GET</Verb>
        <Path>/health</Path>
      </Request>
      <SuccessResponse>
        <ResponseCode>200</ResponseCode>
      </SuccessResponse>
    </HTTPMonitor>
  </HealthMonitor>
</TargetEndpoint>

<!-- Trace is started from the Apigee UI:
     Develop > API Proxies > [proxy name] > Debug tab

     Or via API:
     POST /organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions

     A trace session captures:
     - Every policy that executed and its result
     - All flow variables and their values at each step
     - Request/response headers and body
     - Time spent at each step (ms)
     - Any faults raised and which FaultRule handled them

     Reading a trace:
     - Green step: policy executed successfully
     - Red step:   policy raised a fault
     - Grey step:  policy was skipped (condition was false)
     - Phase markers: ProxyRequest, TargetRequest, TargetResponse, ProxyResponse

     Common debugging workflows:
     1. Variable values wrong: check ExtractVariables step output
     2. Policy not executing: check condition expression in grey steps
     3. Auth failing: check VerifyAPIKey step - red with fault.name
     4. Slow response: check timing at TargetRequest/TargetResponse
     5. Wrong response body: check AssignMessage step output

     IMPORTANT: Trace sessions capture sensitive data (request bodies,
     headers, API keys). Limit trace in production environments. -->

# Method 1: Apigee UI (simplest)
# Develop > API Proxies > + Create > Reverse proxy > OpenAPI Spec
# Paste or upload the OpenAPI spec
# Apigee generates:
#   - ProxyEndpoint with one ConditionalFlow per operation
#   - TargetEndpoint pointing to the servers[0].url from the spec
#   - Basic passthrough proxy (no security policies added yet)

# Method 2: apigeecli
apigeecli apis create oas \
  --name orders-api \
  --oas-base-folderpath ./specs/ \
  --env prod \
  --org my-org \
  --token $(gcloud auth print-access-token)

# Method 3: Apigee Management API
curl -X POST \
  "https://apigee.googleapis.com/v1/organizations/my-org/apis?action=import" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -F "file=@proxy-bundle.zip"

# What the generated proxy includes:
# - One ConditionalFlow per API operation (path + verb)
# - Correct basepath from the spec
# - TargetEndpoint pointing to spec servers URL
# - Does NOT include:
#   - Security policies (add VerifyAPIKey/OAuthV2 manually)
#   - Rate limiting (add Quota/SpikeArrest manually)
#   - Error handling (add FaultRules manually)

# Best practice: use OAS generation as a starting point,
# then add security and policies to the generated bundle

# Monetisation workflow:
#
# 1. API producer creates an API Product (as usual)
# 2. Attaches a Rate Plan to the product
#    - Type: FLAT_FEE, VOLUME_BANDED, REVENUE_SHARE
#    - Charge per API call, per month, or percentage of transaction value
# 3. Developer purchases the plan from the developer portal
#    - Prepaid: loads credits; each call deducts from balance
#    - Postpaid: invoiced at end of billing period
# 4. Apigee enforces quotas and tracks usage for billing
# 5. Revenue reports available in Apigee UI:
#    Monetisation > Reports > Revenue

# Monetisation rate plan types:
#   FLAT_FEE:      Fixed monthly charge for access
#   VOLUME_BANDED: Tiered pricing (first 1k calls free, then $0.001 each)
#   REVENUE_SHARE: API producer takes % of transaction value
#   DEVELOPER:     Developer pays for specific call count bundles

# Minimum Apigee tier: Monetisation requires Apigee Pay-As-You-Go
# or Subscription tier (not available on free tier)

<!-- Reference a flow variable in policy XML using curly braces -->
<AssignMessage name="AM.SetHeader">
  <Set>
    <Headers>
      <!-- Reference built-in variable -->
      <Header name="x-request-path">{request.path}</Header>
      <!-- Reference variable set by ExtractVariables -->
      <Header name="x-order-id">{orderId}</Header>
      <!-- Reference verifyapikey variable -->
      <Header name="x-client-id">{verifyapikey.VerifyAPIKey.client_id}</Header>
    </Headers>
  </Set>
</AssignMessage>

<!-- Reference in a condition expression (no braces needed) -->
<Flow name="OrdersFlow">
  <Condition>request.verb == "GET" and
             proxy.pathsuffix MatchesPath "/orders/**"</Condition>
</Flow>

<!-- Set a variable using JavaScript -->
// context.setVariable("myCustomVar", "hello");
// context.getVariable("request.header.x-api-key");
// var statusCode = context.getVariable("response.status.code");

<!-- Best practice: complete PreFlow with both SpikeArrest and Quota -->
<ProxyEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request>
      <!-- 1. Protect from spikes first -->
      <Step><Name>SpikeArrest</Name></Step>
      <!-- 2. Validate the API key -->
      <Step><Name>VerifyAPIKey</Name></Step>
      <!-- 3. Enforce business quota (after key validation
              so the quota counter knows which developer) -->
      <Step><Name>Quota</Name></Step>
    </Request>
    <Response/>
  </PreFlow>
  <!-- 4. Always have a DefaultFaultRule -->
  <DefaultFaultRule name="DefaultFaultRule">
    <Step><Name>AM.GenericErrorResponse</Name></Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>
</ProxyEndpoint>