Initial commit: add .gitignore and README

API_GATEWAY_MIGRATION_GUIDE.md

@@ -0,0 +1,208 @@
+# 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
+