GCP Cloud Endpoints and API Gateway

Cloud Endpoints and API Gateway are GCP's tools for managing, securing, monitoring, and scaling APIs. An API (Application Programming Interface) is a defined set of HTTP endpoints through which applications communicate. As APIs grow in complexity and usage, they need authentication, rate limiting, analytics, versioning, and documentation. Cloud Endpoints and API Gateway provide these capabilities as managed services.

The Problem APIs Face at Scale

Without API Management:
Client 1 ────────────────────────────▶ Backend Service
Client 2 ────────────────────────────▶ Backend Service
Client 3 ────────────────────────────▶ Backend Service
(No authentication, no rate limiting, no monitoring)

With API Gateway:
Client 1 ──▶ API Gateway ──authenticate──▶ Backend Service
Client 2 ──▶             ──rate limit──▶
Client 3 ──▶             ──log + monitor──▶
            (Single entry point with security + observability)

Cloud Endpoints Overview

Cloud Endpoints is an API management system for APIs hosted on GCP. It provides authentication, monitoring, logging, and rate limiting for REST and gRPC APIs deployed on:

• Compute Engine
• GKE
• App Engine Flexible
• Cloud Run (via Extensible Service Proxy v2 — ESPv2)

Cloud Endpoints Architecture

Client
    │  API request + API key or JWT token
    ▼
Extensible Service Proxy (ESPv2) — sidecar container
    │  Validates authentication
    │  Checks quota / rate limits
    │  Logs request to Cloud Logging
    │  Reports metrics to Cloud Monitoring
    ▼
Backend Service (Cloud Run / GKE pod)
    │  Processes the actual business logic
    ▼
Response returned to client

Defining an API with OpenAPI

Cloud Endpoints uses an OpenAPI specification file (YAML) to define the API contract — endpoints, parameters, authentication, and quotas.

# openapi.yaml — OpenAPI 2.0 spec
swagger: "2.0"
info:
  title: "Product API"
  description: "GCP Endpoints demo API"
  version: "1.0.0"
host: "api.MY_PROJECT_ID.appspot.com"
consumes:
  - "application/json"
produces:
  - "application/json"
schemes:
  - "https"

# Authentication — require an API key for all endpoints
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"

security:
  - api_key: []

paths:
  /products:
    get:
      summary: "List all products"
      operationId: "listProducts"
      responses:
        "200":
          description: "A list of products"

  /products/{product_id}:
    get:
      summary: "Get a product by ID"
      operationId: "getProduct"
      parameters:
        - name: "product_id"
          in: "path"
          required: true
          type: "string"
      responses:
        "200":
          description: "A product object"
        "404":
          description: "Product not found"

# Deploy the API configuration to Cloud Endpoints
gcloud endpoints services deploy openapi.yaml

# Deploy the backend with ESPv2 sidecar (Cloud Run example)
gcloud run deploy product-api \
  --image=gcr.io/my-project/product-api:latest \
  --region=us-central1 \
  --set-env-vars="ENDPOINTS_SERVICE_NAME=api.my-project.appspot.com"

Creating and Using API Keys

# Create an API key in the Console: APIs & Services → Credentials → Create Credentials → API key

# Use the API key in a request
curl "https://api.my-project.appspot.com/products?key=AIzaSyABC123..."

# Without a key → 401 Unauthorized
curl "https://api.my-project.appspot.com/products"
# {"code": 401, "message": "Method doesn't allow unregistered callers"}

API Gateway Overview

API Gateway is a newer, fully managed gateway for serverless backends — specifically Cloud Functions, Cloud Run, and App Engine. Unlike Cloud Endpoints (which uses a sidecar proxy), API Gateway is a standalone managed service. No ESPv2 proxy to deploy or manage.

API Gateway Architecture:
Clients (mobile apps, web apps, third-party integrations)
        │
        ▼
API Gateway (managed, scales automatically)
    │  ├── JWT / Google ID token authentication
    │  ├── API key authentication
    │  ├── Rate limiting per API key
    │  ├── Request logging
    │  └── Traffic routing based on URL path
    │
    ├──▶ Cloud Function: user-service
    ├──▶ Cloud Run: product-service
    └──▶ App Engine: order-service

API Gateway Configuration File

# api-config.yaml — API Gateway config (OpenAPI 3.0)
swagger: "2.0"
info:
  title: my-api
  description: My API Gateway config
  version: "1.0.0"
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  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"

paths:
  /users/{user_id}:
    get:
      summary: Get user profile
      operationId: getUser
      security:
        - google_id_token: []
      parameters:
        - in: path
          name: user_id
          required: true
          type: string
      x-google-backend:
        address: https://user-service-xyz.run.app/users/{user_id}
      responses:
        "200":
          description: User profile

  /products:
    get:
      summary: List products
      operationId: listProducts
      x-google-backend:
        address: https://us-central1-my-project.cloudfunctions.net/listProducts
      responses:
        "200":
          description: Product list

# Create the API Gateway
gcloud api-gateway apis create my-api --project=my-project

# Create an API config from the YAML file
gcloud api-gateway api-configs create v1 \
  --api=my-api \
  --openapi-spec=api-config.yaml \
  --project=my-project

# Deploy the gateway
gcloud api-gateway gateways create my-gateway \
  --api=my-api \
  --api-config=v1 \
  --location=us-central1 \
  --project=my-project

# Get the gateway URL
gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 \
  --project=my-project
# defaultHostname: my-gateway-xyz.uc.gateway.dev

Cloud Endpoints vs API Gateway

API Monitoring with Cloud Endpoints

Cloud Endpoints automatically sends metrics to Cloud Monitoring for every API call:

Cloud Endpoints Metrics (available in Cloud Monitoring):
├── serviceruntime.googleapis.com/api/request_count
│   (Total requests per endpoint per second)
├── serviceruntime.googleapis.com/api/request_latencies
│   (p50, p95, p99 latency by endpoint)
└── serviceruntime.googleapis.com/quota/rate/net_usage
    (API key usage vs quota)

Key Takeaways

• Cloud Endpoints and API Gateway add authentication, rate limiting, logging, and monitoring to APIs.
• Both use OpenAPI specification files to define the API contract and routing rules.
• Cloud Endpoints uses an ESPv2 sidecar proxy deployed alongside the backend service.
• API Gateway is a standalone managed service — no sidecar deployment needed — ideal for serverless backends.
• API keys and JWT tokens (Google ID tokens) are the primary authentication mechanisms.
• API metrics are automatically reported to Cloud Monitoring for usage and latency analysis.