--- name: api-gateway-management description: Manage API gateway including rate limiting, authentication, routing, transformation, monitoring, and API lifecycle management. Use when configuring API gateways, implementing rate limiting, setting up API authentication, managing API versions, or optimizing API performance. Triggers on phrases like "API gateway", "rate limiting", "API authentication", "API routing", "API versioning", "API lifecycle", "throttling", "circuit breaker", "request transformation", "response caching", "API key", "JWT validation", "Kong", "Apigee", "AWS API Gateway", "Azure API Management", "NGINX", "Envoy", "API docs", "OpenAPI", "Swagger". --- # API Gateway Management Manage API gateway including rate limiting, authentication, routing, transformation, monitoring, and API lifecycle management. ## Workflow ### 1. API Gateway Architecture ``` API GATEWAY ARCHITECTURE ═══════════════════════════════════════ Internet ↓ WAF / CDN ↓ API GATEWAY (Kong / Apigee / AWS) ↓ ═══════════════════════════════════ ↓ ↓ ↓ Auth Service Order Service Payment Service ↓ ↓ ↓ PostgreSQL MongoDB Stripe CROSS-CUTTING CONCERNS (Gateway Layer): ═══════════════════════════════════════ → Authentication & Authorization (JWT, OAuth, API keys) → Rate Limiting & Throttling → Request/Response Transformation → Circuit Breaking & Retry → Caching → Logging & Monitoring → IP Whitelisting / Blacklisting → Request Validation (schema) → SSL/TLS Termination → Compression (Gzip/Brotli) → CORS Handling → A/B Testing / Traffic Splitting GATEWAY CONFIGURATION (Kong Example): ═══════════════════════════════════════ Service: orders-service → URL: http://orders.internal:8080 → Host: orders.internal → Port: 8080 → Connect timeout: 5000ms → Write timeout: 10000ms → Read timeout: 10000ms → Retries: 3 Routes: → /api/v1/orders (primary route) → /api/v2/orders (new version) → /orders/deprecated (deprecated, redirect to v2) Plugins: → rate-limiting: 1000 requests/hour per API key → jwt: Validate JWT tokens → cors: Allow origins: *.example.com → request-size-limiting: 10MB max body → ip-restriction: Allow only VPN IPs (admin endpoints) → prometheus: Metrics export → zipkin: Distributed tracing ``` ### 2. Rate Limiting & Throttling ``` RATE LIMITING STRATEGY ═══════════════════════════════════════ Rate Limit Tiers: ═══════════════════════════════════════ Tier Plan Rate Limit Burst Daily Limit ──────────────────────────────────────────────────────────────────────────── Free Free 100 req/hr 10 1,000 Basic $49/mo 1,000 req/hr 50 10,000 Professional $199/mo 5,000 req/hr 200 50,000 Enterprise Custom 50,000 req/hr 1,000 Unlimited Algorithm: Token Bucket ═══════════════════════════════════════ → Bucket fills at rate: R tokens/second → Max bucket size: B tokens (burst capacity) → Each request consumes: N tokens (by endpoint cost) → If tokens < N: Return 429 Too Many Requests Headers (response): X-RateLimit-Limit: 1000 (max requests) X-RateLimit-Remaining: 847 (remaining) X-RateLimit-Reset: 1711900800 (epoch seconds) Retry-After: 60 (seconds to wait) ENDPOINT-SPECIFIC LIMITS: ═══════════════════════════════════════ Endpoint Weight Per-Second Per-Hour Per-Day ──────────────────────────────────────────────────────────────────────────── GET /products 1 10 1,000 10,000 GET /orders 1 5 500 5,000 POST /orders 5 2 200 2,000 POST /payments 10 1 100 1,000 GET /search 2 5 500 5,000 SCOPING: ═══════════════════════════════════════ → Per API key (default) → Per IP address (fallback when no key) → Per user ID (authenticated requests) → Per endpoint (specific limits per route) → Global (total across all endpoints) ``` ### 3. API Authentication & Security ``` API AUTHENTICATION METHODS ═══════════════════════════════════════ Method Use Case Strength Complexity ─────────────────────────────────────────────────────────────────────── API Key Server-to-server MEDIUM LOW JWT User authentication HIGH MEDIUM OAuth 2.0 Third-party access HIGH HIGH mTLS Service-to-service HIGHEST HIGH HMAC Webhook validation HIGH MEDIUM JWT AUTHENTICATION FLOW: ═══════════════════════════════════════ 1. User logs in → Auth server issues JWT 2. Client sends JWT in Authorization header: Authorization: Bearer eyJhbGciOiJSUzI1NiIs... 3. Gateway validates JWT: → Signature verification (RS256, public key) → Expiration check (exp claim) → Issuer validation (iss claim) → Audience validation (aud claim) → Custom claims extraction (role, permissions) 4. If valid: Forward request (with user context) 5. If invalid: Return 401/403 Gateway Plugin (JWT validation): → Public key endpoint: .well-known/jwks.json → Key cache: 1 hour → Clock skew tolerance: 30 seconds → Required claims: sub, exp, iss API SECURITY BEST PRACTICES: ═══════════════════════════════════════ → Rate limiting (prevent abuse) → Request validation (schema enforcement) → Input sanitization (prevent injection) → CORS policy (restrict origins) → HTTPS only (no HTTP) → API key rotation (90 days) → JWT short expiry (15 minutes) + refresh → mTLS for service-to-service → WAF rules (OWASP Top 10) → Audit logging (all API access) ``` ### 4. API Lifecycle Management ``` API LIFECYCLE ═══════════════════════════════════════ Stages: ═══════════════════════════════════════ Design → Develop → Test → Publish → Monitor → Deprecate → Retire VERSIONING STRATEGY: ═══════════════════════════════════════ URL Versioning (recommended): → /api/v1/users → /api/v2/users Header Versioning: → Accept-Version: 2024-01-01 Query Parameter: → /api/users?version=2 DEPRECATION POLICY: ═══════════════════════════════════════ → Minimum support: 12 months after deprecation announcement → Deprecation header: Sunset: Sat, 01 Jun 2025 00:00:00 GMT → Deprecation header: Deprecation: true → Migration guide published (with examples) → Changelog updated → Email notification to API consumers Timeline: T+0: Announce deprecation (v1) T+3mo: Send reminder to all consumers T+6mo: Final warning (monthly) T+12mo: Sunset (v1 returns 410 Gone) API DOCUMENTATION: ═══════════════════════════════════════ → OpenAPI 3.0 spec (automated from code) → Interactive docs (Swagger UI / Redoc) → Code samples (cURL, Python, JavaScript, Java) → SDK generation (OpenAPI Generator) → Postman collection (auto-generated) → Changelog (version history) ``` ### 5. API Monitoring & Analytics ``` API MONITORING ═══════════════════════════════════════ Key Metrics: ═══════════════════════════════════════ → Request rate (RPS) — capacity planning → Error rate (4xx, 5xx) — quality indicator → Latency (P50, P95, P99) — performance → Bandwidth (MB/day) — cost tracking → Cache hit ratio — optimization → Rate limit hits — abuse detection → Auth failures — security → Top consumers — usage analysis → Top endpoints — optimization priority Dashboard: → Real-time: Current RPS, error rate, latency → Hourly: Trends, anomalies → Daily: Usage by consumer, endpoint → Weekly: SLA compliance, growth ALERTING: ═══════════════════════════════════════ Alert Condition Action ──────────────────────────────────────────────────────────────────── High error rate 5xx > 1% for 5 min Page on-call Latency spike P99 > 1s for 5 min Alert team Rate limit breach > 10K limit hits/hour Investigate Auth failure spike > 100 failures/min Security alert New 404 spike > 50 404s/min Check routing Traffic anomaly > 3x normal Investigate API USAGE REPORT: ═══════════════════════════════════════ Top Consumers (this month): 1. Mobile App: 15M requests (35%) 2. Web Frontend: 10M requests (23%) 3. Partner API: 5M requests (12%) 4. Internal Tools: 3M requests (7%) 5. Third-party: 2M requests (5%) 6. Other: 5M requests (18%) Top Endpoints: 1. GET /products: 20M requests (47%) 2. GET /orders: 8M requests (19%) 3. POST /orders: 3M requests (7%) 4. GET /search: 4M requests (9%) 5. Other: 8M requests (18%) ``` ## Edge Cases - **Burst traffic**: Social media viral, marketing campaigns - **Geographic**: Multi-region API routing, latency optimization - **Webhook handling**: Retry, validation, idempotency - **GraphQL**: Gateway for GraphQL (schema stitching, federation) - **gRPC**: gRPC gateway (HTTP/2, protobuf) ## Integration Points - **Gateway tools**: Kong, Apigee, AWS API Gateway, Azure APIM, NGINX, Envoy - **Auth**: Auth0, Okta, Keycloak, custom JWT - **Monitoring**: Prometheus, Grafana, Datadog, New Relic - **Docs**: Swagger, Redoc, Stoplight, Postman - **Analytics**: Mixpanel, Segment, custom dashboards - **Security**: WAF, Cloudflare, OAuth providers ## Output ### API Gateway Status ``` API GATEWAY STATUS — Q4 2024 ═══════════════════════════════════════ APIs managed: 24 (8 v1, 12 v2, 4 v3) Monthly requests: 42M P99 latency: 250ms (target: <500ms) ✓ Error rate: 0.03% (target: <0.1%) ✓ SLA compliance: 99.97% ✓ Rate limits active: 156 (per tier) Deprecated APIs: 2 (sunset Jun 2025) Documentation: OpenAPI 3.0, auto-generated Top consumer: Mobile App (35% of traffic) ```