Api Gateway Builder

---
name: api-gateway-builder
description: |
  Expert guide for designing and configuring API gateways including Kong, AWS API Gateway, and cloud-native solutions. Covers rate limiting, authentication, routing, throttling, request transformation, caching, and production deployment patterns.
  Use when the user asks about api gateway builder, api gateway builder best practices, or needs guidance on api gateway builder implementation.
  Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license: Apache-2.0
metadata:
  author: foundry-skills
  version: "1.0.0"
  tags: "backend api-design guide"
  category: "backend-systems"
  subcategory: "api-design"
  depends: ""
  disclaimer: "none"
  difficulty: "advanced"
---

# API Gateway Builder

You are an expert in designing and operating API gateway infrastructure. You guide teams through gateway selection, routing configuration, rate limiting, authentication integration, request/response transformation, and production operations for both self-managed and cloud-native API gateways.

## Core Principles

1. **Gateway is the front door** - It handles cross-cutting concerns so services do not have to.
2. **Fail open vs fail closed** - Authentication must fail closed; rate limiting can fail open under extreme load.
3. **Keep the gateway thin** - Route, authenticate, rate limit, transform. Never put business logic in the gateway.

## Gateway Selection

```
GATEWAY              TYPE            BEST FOR                   COST MODEL
---------------------------------------------------------------------------
AWS API GW (HTTP)    Managed         Serverless, low complexity $1/million reqs
AWS API GW (REST)    Managed         WebSocket, caching, WAF    $3.50/million
Kong                 Self-managed    Multi-cloud, plugins, K8s  Open source/EE
Envoy / Istio        Self-managed    Service mesh, gRPC         Free (infra cost)
Traefik              Self-managed    Docker/K8s auto-discovery  Open source/EE
NGINX                Self-managed    Max performance, mature    Open source/Plus
```

```
CHOOSE AWS API GW:  Serverless backend, AWS-native, <10K req/s
CHOOSE KONG:        Multi-cloud, complex plugins, Kubernetes-native
CHOOSE ENVOY:       Service mesh, gRPC-native, fine-grained traffic control
CHOOSE NGINX:       Maximum raw performance, simple routing needs
```

## Kong Configuration

### Declarative Config (kong.yml)

```yaml
_format_version: "3.0"

services:
  - name: user-service
    url: [reference URL]
    connect_timeout: 5000
    read_timeout: 30000
    retries: 3
    routes:
      - name: user-routes
        paths: [/api/v1/users]
        methods: [GET, POST, PUT, DELETE]
        strip_path: false
        protocols: [https]

plugins:
  - name: rate-limiting
    config:
      minute: 100
      hour: 5000
      policy: redis
      redis_host: redis
      fault_tolerant: true        # Fail open if Redis down

  - name: correlation-id
    config:
      header_name: X-Request-ID
      generator: uuid
      echo_downstream: true

  - name: request-size-limiting
    config:
      allowed_payload_size: 10    # MB
```

### Service-Level Plugins

```yaml
plugins:
  - name: rate-limiting
    route: login-route
    config:
      minute: 10                  # Strict limit on login attempts

  - name: jwt
    service: user-service
    config:
      claims_to_verify: [exp]
      header_names: [Authorization]

  - name: request-transformer
    service: user-service
    config:
      add:
        headers: ["X-Gateway-Version:1.0"]
      remove:
        headers: [Cookie]
```

### Kong in Kubernetes

```yaml
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit-api
plugin: rate-limiting
config:
  minute: 100
  policy: local
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user-api
  annotations:
    konghq.com/plugins: rate-limit-api,jwt-auth
spec:
  ingressClassName: kong
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api/v1/users
            pathType: Prefix
            backend:
              service: { name: user-service, port: { number: 8080 } }
```

## AWS API Gateway

### HTTP API (Recommended)

```yaml
Resources:
  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: prod
      CorsConfiguration:
        AllowOrigins: ["[reference URL]"]
        AllowMethods: [GET, POST, PUT, DELETE]
        AllowHeaders: [Authorization, Content-Type]
      Auth:
        DefaultAuthorizer: JWTAuthorizer
        Authorizers:
          JWTAuthorizer:
            IdentitySource: $request.header.Authorization
            JwtConfiguration:
              issuer: [reference URL]
              audience: [api.example.com]
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
        ThrottlingRateLimit: 100
```

### REST API with Usage Plans

```yaml
  UsagePlan:
    Type: AWS::ApiGateway::UsagePlan
    Properties:
      Throttle:
        BurstLimit: 200
        RateLimit: 100
      Quota:
        Limit: 100000
        Period: MONTH
```

## Rate Limiting

### Algorithm Comparison

```
ALGORITHM           HOW IT WORKS                    TRADE-OFF
---------------------------------------------------------------------------
Fixed Window        Count per time window            Simple; burst at edges
Sliding Window      Weighted current + previous      Good accuracy/memory
Token Bucket        Tokens refill at steady rate     Allows controlled bursts
Leaky Bucket        Process at fixed rate, queue     Smooth; no bursts
```

### Multi-Tier Strategy

```
TIER        KEY              LIMIT           PURPOSE
--------------------------------------------------------------
Global      -                10,000 req/s    Protect infrastructure
Per-IP      client IP        100 req/min     Prevent abuse
Per-User    auth token/key   1,000 req/hr    Fair usage
Per-Route   path + method    50 req/min      Protect heavy endpoints
```

### Rate Limit Response

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
```

## Authentication Patterns

### Gateway Auth Flow

```
Client -> Gateway -> [Auth Plugin] -> Backend Service
                         |
                    Validate token
                    Extract claims
                    Inject headers:
                      X-User-ID, X-User-Role, X-Tenant-ID
                         |
                    Strip Authorization header
                    (backend trusts gateway headers)
```

### API Key Authentication

```yaml
plugins:
  - name: key-auth
    service: api-service
    config:
      key_names: [X-API-Key, apikey]
      key_in_header: true
      key_in_query: true
      hide_credentials: true      # Remove key before proxying
```

## Request/Response Transformation

```yaml
# Add security headers to all responses
plugins:
  - name: response-transformer
    config:
      add:
        headers:
          - "Strict-Transport-Security:max-age=31536000; includeSubDomains"
          - "X-Content-Type-Options:nosniff"
          - "X-Frame-Options:DENY"
      remove:
        headers: [Server, X-Powered-By]
```

## Routing Patterns

```
PATH-BASED:
  /api/v1/users/*     -> user-service:8080
  /api/v1/orders/*    -> order-service:8080
  /api/v2/users/*     -> user-service-v2:8080

HEADER-BASED (e.g., mobile vs web):
  X-Client-Type: mobile  -> user-service-mobile
  X-Client-Type: web     -> user-service-web

CANARY RELEASES:
  10% traffic -> canary backend
  90% traffic -> stable backend
  Sticky routing per consumer for consistency
```

## Caching

```yaml
plugins:
  - name: proxy-cache
    config:
      strategy: redis
      content_type: [application/json]
      request_method: [GET, HEAD]
      response_code: [200, 301]
      cache_ttl: 300
      vary_headers: [Authorization, Accept-Encoding]
      cache_control: true         # Respect Cache-Control headers
```

## Health Checks

```yaml
upstreams:
  - name: user-service
    healthchecks:
      active:
        http_path: /health
        healthy: { interval: 5, successes: 3 }
        unhealthy: { interval: 5, http_failures: 3, timeouts: 3 }
      passive:
        healthy: { successes: 5 }
        unhealthy: { http_failures: 5, timeouts: 3 }
    targets:
      - { target: "user-service-1:8080", weight: 100 }
      - { target: "user-service-2:8080", weight: 100 }
```

## Monitoring

```
METRIC                      ALERT CONDITION
------------------------------------------------------
Request rate                Sudden spike or drop
Error rate (5xx)            > 1% sustained
Latency (p99)               > 2s
Rate limit hits             Sustained high rate
Auth failures               Spike (possible attack)
Upstream health             Any backend unhealthy
Cache hit ratio             < 50%
```

## Production Checklist

```
ROUTING:
  [ ] All routes use HTTPS
  [ ] API versioning implemented
  [ ] Health check endpoints excluded from auth

SECURITY:
  [ ] Auth enforced on all non-public routes
  [ ] Rate limiting (global, per-user, per-route)
  [ ] Request size limits set
  [ ] Security headers on all responses
  [ ] CORS with explicit allowed origins
  [ ] Sensitive headers stripped before proxying

RELIABILITY:
  [ ] Upstream health checks (active + passive)
  [ ] Timeouts on all upstream connections
  [ ] Circuit breaker for failing backends
  [ ] Graceful degradation documented

OBSERVABILITY:
  [ ] Access logging (structured JSON)
  [ ] Metrics exported (Prometheus/CloudWatch)
  [ ] Distributed tracing propagated
  [ ] Alerting on error rate, latency, rate limits
```

## When to Use

**Use this skill when:**
- Designing or implementing api gateway builder solutions
- Reviewing or improving existing api gateway builder approaches
- Making architectural or implementation decisions about api gateway builder
- Learning api gateway builder patterns and best practices
- Troubleshooting api gateway builder-related issues

**Do NOT use this skill when:**
- The question is about a fundamentally different technology domain
- A more specific sibling skill covers the exact topic needed
- The user needs a complete hands-on tutorial rather than expert guidance

## Output Format

```markdown
# Api Gateway Builder Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]
```

## Example

**Input:** "Help me implement api gateway builder for a medium-scale production application"

**Output:** A structured analysis covering current state assessment, recommended api gateway builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

## Edge Cases

- **Legacy system integration:** When api gateway builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
- **Scale mismatch:** When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
- **Team skill gaps:** When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
- **Conflicting requirements:** When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities