Api Gateway Patterns

API Gateway Patterns

Expert guidance for implementing API gateways with routing, authentication, traffic management, and service composition patterns for microservices architectures at scale.

When to Use This Skill

• Implementing API gateway infrastructure for microservices
• Designing Backend for Frontend (BFF) layers
• Adding authentication and authorization at the gateway level
• Implementing rate limiting, circuit breakers, and retry logic
• Setting up service discovery and dynamic routing
• Building API composition and aggregation layers
• Managing cross-cutting concerns (logging, monitoring, CORS)
• Evaluating gateway solutions (Kong, Nginx, Envoy, AWS API Gateway)

Core Concepts

Gateway Responsibilities

Routing: Direct requests to appropriate backend services based on path, headers, or host Security: Centralized authentication, authorization, and API key validation Traffic Management: Rate limiting, circuit breakers, retry logic Composition: Aggregate multiple service calls into unified responses Transformation: Modify requests/responses for client optimization or legacy adaptation

Architecture Patterns

Single Gateway: One gateway for all clients (simple, potential bottleneck) BFF Pattern: Separate gateway per client type (mobile, web, admin) - optimized for each GraphQL Gateway: Schema stitching across services, client-driven data fetching Service Mesh: Distributed gateway pattern with sidecar proxies (Istio, Linkerd)

Quick Reference

| Task | Load reference | | --- | --- | | Routing strategies (path, header, host-based) | skills/api-gateway-patterns/references/routing-patterns.md | | Request/response transformation | skills/api-gateway-patterns/references/transformation.md | | API composition and aggregation | skills/api-gateway-patterns/references/composition.md | | Authentication & authorization (JWT, OAuth, RBAC) | skills/api-gateway-patterns/references/authentication.md | | Traffic management (rate limiting, circuit breakers) | skills/api-gateway-patterns/references/traffic-management.md | | Backend for Frontend (BFF) pattern | skills/api-gateway-patterns/references/bff-pattern.md | | Service discovery integration | skills/api-gateway-patterns/references/service-discovery.md | | Gateway implementations (Kong, Nginx, Envoy, AWS) | skills/api-gateway-patterns/references/implementations.md |

Implementation Workflow

Phase 1: Requirements Analysis

1. Identify client types: Mobile, web, admin, partners
2. Map service landscape: Catalog backend services and endpoints
3. Define cross-cutting concerns: Auth, logging, monitoring, CORS
4. Determine composition needs: Which endpoints require aggregation?
5. Establish SLAs: Latency, throughput, availability targets

Phase 2: Gateway Design

1. Choose architecture: Single gateway vs BFF vs GraphQL
2. Select implementation: Kong, Nginx, Envoy, AWS API Gateway
3. Design routing rules: Path-based, header-based, host-based
4. Plan authentication: JWT, OAuth 2.0, API keys, or hybrid
5. Define traffic policies: Rate limits, circuit breakers, timeouts

Phase 3: Implementation

1. Set up infrastructure: Deploy gateway instances, configure load balancer
2. Implement routing: Configure service discovery and route definitions
3. Add authentication: JWT validation, OAuth integration, API key management
4. Apply traffic management: Rate limiting, circuit breakers, retry logic
5. Enable observability: Distributed tracing, metrics, structured logging

Phase 4: Testing & Optimization

1. Load testing: Verify performance under expected and peak load
2. Failure injection: Test circuit breakers and retry logic
3. Security testing: Verify auth flows, token validation, RBAC policies
4. Latency optimization: Cache strategies, connection pooling
5. Monitor and tune: Adjust timeouts, limits based on real traffic

Best Practices

1. Centralize Cross-Cutting Concerns: Authentication, logging, monitoring at gateway
2. Keep Gateway Lightweight: Avoid complex business logic, delegate to services
3. Implement Health Checks: Monitor upstream service health, remove unhealthy instances
4. Use Circuit Breakers: Prevent cascading failures, fail fast
5. Apply Rate Limiting: Protect services from overload, implement tiered limits
6. Enable Observability: Distributed tracing, metrics, structured logging
7. Version APIs: Support multiple API versions, plan deprecation
8. Secure Communication: TLS everywhere, mutual TLS for service-to-service
9. Cache Strategically: Response caching, but invalidate properly
10. Test Resilience: Chaos engineering, failure injection, load testing

Common Mistakes

1. Business Logic in Gateway: Keep gateway focused on routing/security, not business rules
2. Chatty Composition: Too many upstream calls (use BFF, GraphQL, or caching)
3. Single Point of Failure: Deploy redundantly, use load balancers
4. No Timeout Configuration: Always set connection/read timeouts to prevent hanging requests
5. Ignoring Backpressure: Implement queue limits, graceful degradation
6. Over-Aggregation: Don't make gateway do too much work (compute-heavy transformations)
7. Inadequate Monitoring: Must track latency, errors, throughput at gateway level
8. No Rate Limiting: Services will be overwhelmed eventually without protection
9. Synchronous Everything: Use async patterns for non-critical operations
10. No Version Strategy: Breaking changes break all clients simultaneously

Resources

• Kong: https://docs.konghq.com/gateway/latest/
• Nginx: https://nginx.org/en/docs/
• Envoy: https://www.envoyproxy.io/docs/envoy/latest/
• AWS API Gateway: https://docs.aws.amazon.com/apigateway/
• Patterns: "Microservices Patterns" by Chris Richardson
• Service Mesh: https://istio.io/latest/docs/
• Circuit Breakers: Martin Fowler's CircuitBreaker pattern
• BFF Pattern: Sam Newman's "Building Microservices"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NickCrew
• Source: NickCrew/Claude-Cortex
• License: MIT
• Homepage: https://cortex.atlascrew.dev/

Install and usage instructions live in the source repository linked above.