API Gateway Patterns

API Gateway Patterns

A comprehensive skill for implementing production-grade API gateways using Kong and industry best practices. This skill covers advanced routing, authentication, rate limiting, load balancing, traffic management, and observability patterns for microservices architectures.

When to Use This Skill

Use this skill when:

• Implementing an API gateway for microservices architectures
• Managing traffic routing, load balancing, and service discovery
• Implementing authentication and authorization at the gateway level
• Enforcing rate limiting, quotas, and traffic policies
• Adding observability, logging, and monitoring to API traffic
• Implementing request/response transformation and caching
• Managing API versioning and deprecation strategies
• Setting up circuit breakers and resilience patterns
• Configuring multi-environment API deployments
• Implementing API security policies (CORS, CSRF, WAF)
• Building developer portals and API documentation
• Managing API lifecycle from development to production

Core Concepts

API Gateway Architecture

An API gateway acts as a single entry point for client applications, routing requests to appropriate backend services while providing cross-cutting concerns:

• Reverse Proxy: Routes client requests to backend services
• API Composition: Aggregates multiple service calls into single responses
• Protocol Translation: Converts between protocols (HTTP, gRPC, WebSocket)
• Cross-Cutting Concerns: Authentication, logging, rate limiting, caching
• Traffic Management: Load balancing, circuit breaking, retries
• Security: SSL termination, API key validation, OAuth2 flows

Key Gateway Components

1. Services: Upstream APIs that the gateway proxies to
2. Routes: Request matching rules that determine service routing
3. Upstreams: Load balancer configurations for service instances
4. Plugins: Extensible middleware for features (auth, logging, etc.)
5. Consumers: API clients with authentication credentials
6. Certificates: SSL/TLS certificates for secure communication
7. SNIs: Server Name Indication for multi-domain SSL

Kong Gateway Fundamentals

Kong is a cloud-native, platform-agnostic, scalable API gateway:

Architecture:

• Control Plane: Admin API for configuration management
• Data Plane: Proxy layer handling runtime traffic
• Database: PostgreSQL or Cassandra for config storage (or DB-less mode)
• Plugin System: Lua-based extensibility for custom logic

Core Entities:

Service (upstream API)
  └── Routes (request matching)
       └── Plugins (features/policies)

Upstream (load balancer)
  └── Targets (service instances)

Consumer (API client)
  └── Credentials (auth keys/tokens)
       └── Plugins (consumer-specific policies)

Routing Patterns

Pattern 1: Path-Based Routing

Route requests based on URL paths to different backend services.

Use Case: Microservices with distinct URL prefixes (e.g., /users, /orders, /products)

Configuration:

# Users Service
service:
  name: users-service
  url: http://users-api:8001

routes:
  - name: users-route
    paths:
      - /users
      - /api/users
    strip_path: true
    methods:
      - GET
      - POST
      - PUT
      - DELETE

# Orders Service
service:
  name: orders-service
  url: http://orders-api:8002

routes:
  - name: orders-route
    paths:
      - /orders
      - /api/orders
    strip_path: true

Key Options:

• strip_path: true - Removes matched path before proxying (e.g., /users/123 → /123)
• strip_path: false - Preserves full path (e.g., /users/123 → /users/123)
• preserve_host: true - Forwards original Host header to upstream

Pattern 2: Header-Based Routing

Route based on HTTP headers for A/B testing, canary deployments, or API versioning.

Use Case: Gradual rollout of new API versions or feature flags

Configuration:

# V1 Service (stable)
service:
  name: api-v1
  url: http://api-v1:8001

routes:
  - name: api-v1-route
    paths:
      - /api
    headers:
      X-API-Version:
        - "1"
        - "1.0"

# V2 Service (beta)
service:
  name: api-v2
  url: http://api-v2:8002

routes:
  - name: api-v2-route
    paths:
      - /api
    headers:
      X-API-Version:
        - "2"
        - "2.0"

# Default route (no version header)
routes:
  - name: api-default
    paths:
      - /api
    # Routes to V1 by default

Advanced Header Routing:

# Mobile vs Web routing
routes:
  - name: mobile-api
    headers:
      User-Agent:
        - ".*Mobile.*"
        - ".*Android.*"
        - ".*iOS.*"
    service: mobile-optimized-api

  - name: web-api
    headers:
      User-Agent:
        - ".*Chrome.*"
        - ".*Firefox.*"
        - ".*Safari.*"
    service: web-api

Pattern 3: Method-Based Routing

Route different HTTP methods to specialized services.

Use Case: CQRS pattern - separate read and write services

Configuration:

# Read Service (queries)
service:
  name: query-service
  url: http://read-api:8001

routes:
  - name: read-operations
    paths:
      - /api/resources
    methods:
      - GET
      - HEAD
      - OPTIONS

# Write Service (commands)
service:
  name: command-service
  url: http://write-api:8002

routes:
  - name: write-operations
    paths:
      - /api/resources
    methods:
      - POST
      - PUT
      - PATCH
      - DELETE

Pattern 4: Host-Based Routing

Route based on the requested hostname for multi-tenant applications.

Use Case: Different subdomains for different customers or environments

Configuration:

# Tenant A
service:
  name: tenant-a-api
  url: http://tenant-a:8001

routes:
  - name: tenant-a-route
    hosts:
      - tenant-a.api.example.com
      - a.api.example.com

# Tenant B
service:
  name: tenant-b-api
  url: http://tenant-b:8002

routes:
  - name: tenant-b-route
    hosts:
      - tenant-b.api.example.com
      - b.api.example.com

# Wildcard for dynamic tenants
routes:
  - name: dynamic-tenant
    hosts:
      - "*.api.example.com"
    service: multi-tenant-api

Pattern 5: Weighted Routing (Canary Deployments)

Gradually shift traffic between service versions.

Implementation:

# Create two upstreams with weight distribution
upstream:
  name: api-upstream
  algorithm: round-robin

targets:
  - target: api-v1:8001
    weight: 90  # 90% traffic to stable version

  - target: api-v2:8002
    weight: 10  # 10% traffic to canary version

service:
  name: api-service
  host: api-upstream  # Points to upstream

routes:
  - name: api-route
    paths:
      - /api

Gradual Rollout Strategy:

1. Start: 100% v1, 0% v2
2. Phase 1: 90% v1, 10% v2 (monitor metrics)
3. Phase 2: 75% v1, 25% v2
4. Phase 3: 50% v1, 50% v2
5. Phase 4: 25% v1, 75% v2
6. Complete: 0% v1, 100% v2

Rate Limiting Patterns

Pattern 1: Global Rate Limiting

Protect your entire API from abuse with global limits.

Use Case: Prevent DDoS attacks and ensure fair usage

Configuration:

plugins:
  - name: rate-limiting
    config:
      minute: 1000
      hour: 10000
      day: 100000
      policy: local  # or 'cluster', 'redis'
      fault_tolerant: true
      hide_client_headers: false
      limit_by: ip  # or 'consumer', 'credential', 'service'

Policy Options:

• local: In-memory, single node (not cluster-safe)
• cluster: Shared across Kong nodes via database
• redis: High-performance distributed limiting via Redis

Pattern 2: Consumer-Specific Rate Limiting

Different limits for different API consumers (tiers).

Use Case: Freemium model with tiered pricing

Configuration:

# Free tier consumer
consumer:
  username: free-user-123

plugins:
  - name: rate-limiting
    consumer: free-user-123
    config:
      minute: 10
      hour: 100
      day: 1000

# Premium tier consumer
consumer:
  username: premium-user-456

plugins:
  - name: rate-limiting