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
- Identify client types: Mobile, web, admin, partners
- Map service landscape: Catalog backend services and endpoints
- Define cross-cutting concerns: Auth, logging, monitoring, CORS
- Determine composition needs: Which endpoints require aggregation?
- Establish SLAs: Latency, throughput, availability targets
Phase 2: Gateway Design
- Choose architecture: Single gateway vs BFF vs GraphQL
- Select implementation: Kong, Nginx, Envoy, AWS API Gateway
- Design routing rules: Path-based, header-based, host-based
- Plan authentication: JWT, OAuth 2.0, API keys, or hybrid
- Define traffic policies: Rate limits, circuit breakers, timeouts
Phase 3: Implementation
- Set up infrastructure: Deploy gateway instances, configure load balancer
- Implement routing: Configure service discovery and route definitions
- Add authentication: JWT validation, OAuth integration, API key management
- Apply traffic management: Rate limiting, circuit breakers, retry logic
- Enable observability: Distributed tracing, metrics, structured logging
Phase 4: Testing & Optimization
- Load testing: Verify performance under expected and peak load
- Failure injection: Test circuit breakers and retry logic
- Security testing: Verify auth flows, token validation, RBAC policies
- Latency optimization: Cache strategies, connection pooling
- Monitor and tune: Adjust timeouts, limits based on real traffic
Best Practices
- Centralize Cross-Cutting Concerns: Authentication, logging, monitoring at gateway
- Keep Gateway Lightweight: Avoid complex business logic, delegate to services
- Implement Health Checks: Monitor upstream service health, remove unhealthy instances
- Use Circuit Breakers: Prevent cascading failures, fail fast
- Apply Rate Limiting: Protect services from overload, implement tiered limits
- Enable Observability: Distributed tracing, metrics, structured logging
- Version APIs: Support multiple API versions, plan deprecation
- Secure Communication: TLS everywhere, mutual TLS for service-to-service
- Cache Strategically: Response caching, but invalidate properly
- Test Resilience: Chaos engineering, failure injection, load testing
Common Mistakes
- Business Logic in Gateway: Keep gateway focused on routing/security, not business rules
- Chatty Composition: Too many upstream calls (use BFF, GraphQL, or caching)
- Single Point of Failure: Deploy redundantly, use load balancers
- No Timeout Configuration: Always set connection/read timeouts to prevent hanging requests
- Ignoring Backpressure: Implement queue limits, graceful degradation
- Over-Aggregation: Don't make gateway do too much work (compute-heavy transformations)
- Inadequate Monitoring: Must track latency, errors, throughput at gateway level
- No Rate Limiting: Services will be overwhelmed eventually without protection
- Synchronous Everything: Use async patterns for non-critical operations
- 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"