docs/API_GATEWAY_MIGRATION_GUIDE.md

API Gateway Migration Guide

Date: 2025-01-27 Purpose: Guide for migrating projects to unified API gateway Status: Complete

---

Overview

This guide provides instructions for migrating projects to use the unified API gateway for routing, authentication, and rate limiting.

---

Migration Steps

Step 1: Review Current API Setup

1. Document current API endpoints
2. Identify authentication mechanisms
3. Note rate limiting requirements
4. List required headers/query parameters

Step 2: Register Service with API Gateway

Service Registration

# api-gateway/services/my-service.yaml
apiVersion: gateway.example.com/v1
kind: Service
metadata:
  name: my-service
spec:
  backend:
    url: http://my-service:8080
    healthCheck: /health
  routes:
    - path: /api/my-service
      methods: [GET, POST, PUT, DELETE]
      authentication:
        required: true
        type: JWT
      rateLimit:
        requests: 100
        window: 1m

Step 3: Update Client Applications

Update API Endpoints

Before:

const response = await fetch('https://my-service.example.com/api/users');

After:

const response = await fetch('https://api.example.com/api/my-service/users', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Step 4: Configure Authentication

JWT Authentication

The API gateway handles JWT validation:

// Client sends JWT token
const token = await getAuthToken();
const response = await fetch('https://api.example.com/api/my-service/users', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

API Key Authentication

const response = await fetch('https://api.example.com/api/my-service/users', {
  headers: {
    'X-API-Key': apiKey
  }
});

Step 5: Update Rate Limiting

Rate limiting is handled by the gateway:

rateLimit:
  requests: 100
  window: 1m
  burst: 20

Client should handle rate limit responses:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(parseInt(retryAfter) * 1000);
  // Retry request
}

---

Configuration Examples

Route Configuration

routes:
  - path: /api/my-service/users
    methods: [GET]
    authentication:
      required: true
      roles: [user, admin]
    rateLimit:
      requests: 100
      window: 1m
    cors:
      allowedOrigins: ["https://app.example.com"]
      allowedMethods: [GET, POST]

Service Health Check

healthCheck:
  path: /health
  interval: 30s
  timeout: 5s
  failureThreshold: 3

---

Best Practices

Authentication

• Use JWT tokens for stateless auth
• Validate tokens at gateway
• Pass user context to services

Rate Limiting

• Set appropriate limits per endpoint
• Use different limits for authenticated/unauthenticated
• Implement client-side retry logic

Monitoring

• Log all requests at gateway
• Track response times
• Monitor error rates
• Set up alerts

---

Troubleshooting

401 Unauthorized

Check:

• Token validity
• Token expiration
• Required roles/permissions

429 Too Many Requests

Check:

• Rate limit configuration
• Client request frequency
• Burst limits

502 Bad Gateway

Check:

• Backend service health
• Network connectivity
• Service endpoint configuration

---

Migration Checklist

• Review current API setup
• Register service with gateway
• Configure routes
• Set up authentication
• Configure rate limiting
• Update client applications
• Test endpoints
• Monitor metrics
• Update documentation
• Deprecate old endpoints

---

Last Updated: 2025-01-27