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

```yaml
# 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**:
```typescript
const response = await fetch('https://my-service.example.com/api/users');
```

**After**:
```typescript
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:

```typescript
// 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

```typescript
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:

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

Client should handle rate limit responses:

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

---

## Configuration Examples

### Route Configuration

```yaml
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

```yaml
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