API Gateway & Cloud Endpoints

# openapi-spec.yaml
swagger: "2.0"
info:
  title: "Orders API"
  description: "API for managing customer orders"
  version: "1.0.0"
host: "orders-api-abc123.apigateway.my-project.cloud.goog"
schemes:
  - "https"
produces:
  - "application/json"
consumes:
  - "application/json"

# Security definitions
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "x-api-key"
    in: "header"
  firebase_auth:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://securetoken.google.com/my-project"
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
    x-google-audiences: "my-project"

# API key quota limits
x-google-management:
  metrics:
    - name: "read-requests"
      displayName: "Read Requests"
      valueType: INT64
      metricKind: DELTA
    - name: "write-requests"
      displayName: "Write Requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
      - name: "write-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 100

paths:
  /orders:
    get:
      summary: "List orders"
      operationId: "listOrders"
      security:
        - api_key: []
      x-google-quota:
        metricCosts:
          read-requests: 1
      x-google-backend:
        address: "https://orders-service-abc123.run.app/orders"
        deadline: 30.0
      parameters:
        - name: "page_size"
          in: "query"
          type: "integer"
          default: 20
        - name: "page_token"
          in: "query"
          type: "string"
      responses:
        "200":
          description: "Successful response"
        "401":
          description: "Unauthorized"
        "429":
          description: "Rate limit exceeded"
    post:
      summary: "Create an order"
      operationId: "createOrder"
      security:
        - firebase_auth: []
      x-google-quota:
        metricCosts:
          write-requests: 1
      x-google-backend:
        address: "https://orders-service-abc123.run.app/orders"
        deadline: 30.0
      responses:
        "201":
          description: "Order created"

  /orders/{orderId}:
    get:
      summary: "Get order by ID"
      operationId: "getOrder"
      security:
        - api_key: []
        - firebase_auth: []
      x-google-backend:
        address: "https://orders-service-abc123.run.app/orders/{orderId}"
        path_translation: APPEND_PATH_TO_ADDRESS
      parameters:
        - name: "orderId"
          in: "path"
          required: true
          type: "string"
      responses:
        "200":
          description: "Successful response"
        "404":
          description: "Order not found"

# Enable required APIs
gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

# Create the API resource
gcloud api-gateway apis create orders-api \
  --display-name="Orders API"

# Create an API config from the OpenAPI spec
gcloud api-gateway api-configs create orders-v1 \
  --api=orders-api \
  --openapi-spec=openapi-spec.yaml \
  --backend-auth-service-account=api-gateway-sa@my-project.iam.gserviceaccount.com

# Create a gateway (deploys the API to a region)
gcloud api-gateway gateways create orders-gateway \
  --api=orders-api \
  --api-config=orders-v1 \
  --location=us-central1

# Get the gateway URL
gcloud api-gateway gateways describe orders-gateway \
  --location=us-central1 \
  --format='value(defaultHostname)'

# Create an API key for testing
gcloud services api-keys create \
  --display-name="Test API Key" \
  --api-target=service=orders-api-abc123.apigateway.my-project.cloud.goog

# Test the API
curl -H "x-api-key: YOUR_API_KEY" \
  https://orders-gateway-abc123.uc.gateway.dev/orders

# Update to a new config version
gcloud api-gateway api-configs create orders-v2 \
  --api=orders-api \
  --openapi-spec=openapi-spec-v2.yaml \
  --backend-auth-service-account=api-gateway-sa@my-project.iam.gserviceaccount.com

gcloud api-gateway gateways update orders-gateway \
  --api=orders-api \
  --api-config=orders-v2 \
  --location=us-central1

# Step 1: Deploy the backend service to Cloud Run
gcloud run deploy orders-backend \
  --image=us-central1-docker.pkg.dev/my-project/images/orders-api:latest \
  --region=us-central1 \
  --no-allow-unauthenticated \
  --platform=managed

# Step 2: Deploy the OpenAPI spec to Service Management
gcloud endpoints services deploy openapi-spec.yaml

# Step 3: Build the ESPv2 container with your service config
chmod +x gcloud_build_image
./gcloud_build_image -s orders-api.endpoints.my-project.cloud.goog \
  -c 2023-01-15r0 \
  -p my-project

# Step 4: Deploy ESPv2 as the public-facing Cloud Run service
gcloud run deploy orders-api-gateway \
  --image=gcr.io/my-project/endpoints-runtime-serverless:orders-api.endpoints.my-project.cloud.goog-2023-01-15r0 \
  --region=us-central1 \
  --allow-unauthenticated \
  --set-env-vars=ESPv2_ARGS=--cors_preset=cors_with_regex \
  --platform=managed

# Step 5: Verify the deployment
GATEWAY_URL=$(gcloud run services describe orders-api-gateway \
  --region=us-central1 --format='value(status.url)')
curl "$GATEWAY_URL/orders" -H "x-api-key: YOUR_API_KEY"

# Provision Apigee X organization (typically done once)
gcloud apigee organizations provision \
  --project=my-project \
  --authorized-network=default \
  --runtime-location=us-central1 \
  --analytics-region=us-central1

# Create an environment
gcloud apigee environments create prod \
  --organization=my-project \
  --display-name="Production"

# Create an environment group (for custom domains)
gcloud apigee envgroups create prod-group \
  --organization=my-project \
  --hostnames=api.example.com

# Attach environment to group
gcloud apigee envgroups attachments create \
  --organization=my-project \
  --envgroup=prod-group \
  --environment=prod

# Deploy an API proxy (from a bundle)
gcloud apigee apis deploy \
  --organization=my-project \
  --environment=prod \
  --api=orders-api \
  --revision=1

# List deployed API proxies
gcloud apigee apis list --organization=my-project

# Create a developer
gcloud apigee developers create \
  --organization=my-project \
  --email=dev@example.com \
  --first-name=Jane \
  --last-name=Developer \
  --user-name=jdeveloper

# Create an API product (bundle of APIs with quotas)
gcloud apigee products create orders-product \
  --organization=my-project \
  --display-name="Orders API - Free Tier" \
  --apis=orders-api \
  --environments=prod \
  --quota=1000 \
  --quota-interval=1 \
  --quota-unit=hour \
  --approval-type=auto

# Security definitions supporting multiple auth methods
securityDefinitions:
  # API Key authentication
  api_key:
    type: "apiKey"
    name: "x-api-key"
    in: "header"

  # Google ID Token (for GCP service-to-service)
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    x-google-audiences: "orders-api.endpoints.my-project.cloud.goog"

  # Firebase Authentication
  firebase:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://securetoken.google.com/my-project"
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
    x-google-audiences: "my-project"

  # Auth0 (third-party OIDC provider)
  auth0:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://my-tenant.auth0.com/"
    x-google-jwks_uri: "https://my-tenant.auth0.com/.well-known/jwks.json"
    x-google-audiences: "https://api.example.com"

paths:
  /public/status:
    get:
      summary: "Public health check (no auth)"
      security: []  # Override global security
      x-google-backend:
        address: "https://my-service.run.app/status"
      responses:
        "200":
          description: "Service is healthy"

  /orders:
    get:
      summary: "List orders (API key required)"
      security:
        - api_key: []
      x-google-backend:
        address: "https://my-service.run.app/orders"
      responses:
        "200":
          description: "Order list"

  /orders/{id}:
    put:
      summary: "Update order (user auth required)"
      security:
        - firebase: []
        - auth0: []
      x-google-backend:
        address: "https://my-service.run.app/orders/{id}"
      responses:
        "200":
          description: "Order updated"

# Advanced quota configuration with tiered limits
x-google-management:
  metrics:
    - name: "api-requests"
      displayName: "Total API Requests"
      valueType: INT64
      metricKind: DELTA
    - name: "write-operations"
      displayName: "Write Operations"
      valueType: INT64
      metricKind: DELTA
    - name: "heavy-operations"
      displayName: "Heavy Operations (reports, exports)"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # General API request limit
      - name: "api-request-limit"
        metric: "api-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 600  # 10 requests/second default
      # Write operation limit (more restrictive)
      - name: "write-limit"
        metric: "write-operations"
        unit: "1/min/{project}"
        values:
          STANDARD: 60   # 1 write/second default
      # Heavy operation limit (very restrictive)
      - name: "heavy-operation-limit"
        metric: "heavy-operations"
        unit: "1/min/{project}"
        values:
          STANDARD: 5    # 5 per minute

paths:
  /orders:
    get:
      x-google-quota:
        metricCosts:
          api-requests: 1          # Costs 1 API request
    post:
      x-google-quota:
        metricCosts:
          api-requests: 1
          write-operations: 1      # Costs 1 API request + 1 write
  /reports/generate:
    post:
      x-google-quota:
        metricCosts:
          api-requests: 10         # Costs 10 API requests
          heavy-operations: 1      # Costs 1 heavy operation

# View API Gateway metrics
gcloud monitoring metrics list \
  --filter='metric.type = starts_with("apigateway.googleapis.com")'

# Create an alert for high error rate on API Gateway
gcloud beta monitoring policies create \
  --display-name="API Gateway High Error Rate" \
  --condition-display-name="5xx errors > 1% for 5 min" \
  --condition-filter='resource.type="apigateway.googleapis.com/Gateway"
    AND metric.type="apigateway.googleapis.com/request_count"
    AND metric.labels.response_code_class="5xx"' \
  --condition-threshold-value=10 \
  --condition-threshold-comparison=COMPARISON_GT \
  --condition-threshold-duration=300s \
  --notification-channels=projects/my-project/notificationChannels/CHANNEL_ID

# View API Gateway logs
gcloud logging read 'resource.type="apigateway.googleapis.com/Gateway"' \
  --limit=20 \
  --format='table(timestamp, httpRequest.status, httpRequest.latency, httpRequest.requestUrl)'

# View Cloud Endpoints logs
gcloud logging read 'resource.type="api" AND resource.labels.service="orders-api.endpoints.my-project.cloud.goog"' \
  --limit=20