api-gateway-patterns

What this skill does

# 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:**
```yaml
# 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:**
```yaml
# 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:**
```yaml
# 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:**
```yaml
# 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:**
```yaml
# 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:**
```yaml
# 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:**
```yaml
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:**
```yaml
# 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