API Gateway Pattern
Last Updated: January 8, 2026
In the previous chapter, we learned how services find each other through service discovery.
But consider what happens when external clients, like mobile apps or web browsers, need to interact with your microservices. Should a mobile app call a dozen different services to load a single screen? Should every service implement its own authentication, rate limiting, and SSL termination? The answer to both questions is no.
The API Gateway pattern provides a single entry point for all external clients. Instead of exposing your microservices directly, you place a gateway in front of them that handles routing, security, and other cross-cutting concerns.
The gateway simplifies client interactions and centralizes functionality that would otherwise be duplicated across services.
In this chapter, you will learn:
- Why direct client-to-service communication is problematic
- The core responsibilities of an API Gateway
- Request routing and aggregation patterns
- How gateways handle cross-cutting concerns
- Common implementations and their trade-offs
- When to use an API Gateway and when to avoid it
The API Gateway is one of the most common patterns in microservices architectures. Understanding it is essential for designing scalable, secure, and maintainable systems.
The Problem: Direct Client-to-Service Communication
Imagine a mobile app for an e-commerce platform. The home screen shows product recommendations, the user's cart, recent orders, and promotional banners. Without an API Gateway, the app would need to call multiple services directly.
This approach creates several problems:
Too Many Requests
The client makes multiple round trips over the network. Mobile networks are slow and unreliable. Each request adds latency, increases battery drain, and risks failure.
Tight Coupling
Clients are coupled to the internal service structure. If you split the Order Service into Order and Shipping services, every client must be updated.
Duplicated Cross-Cutting Concerns
Every service must implement authentication, authorization, rate limiting, logging, and SSL. This duplicates code and creates inconsistency.
| Concern | Without Gateway |
|---|---|
| Authentication | Each service validates JWT tokens separately |
| Rate Limiting | Each service tracks its own rate limits |
| SSL Termination | Each service manages certificates |
| Logging | Different formats, different destinations |
| CORS | Configured in each service |
Protocol Mismatch
Internal services might use gRPC, AMQP, or other protocols. External clients typically expect REST or GraphQL over HTTPS.
The Solution: API Gateway
An API Gateway is a server that acts as the single entry point for all client requests. It routes requests to appropriate backend services and handles cross-cutting concerns.
Now the client makes a single request to the gateway, which handles:
- Routing to the appropriate service(s)
- Aggregating responses from multiple services
- Authentication and authorization
- Rate limiting and throttling
- Protocol translation
- Response transformation
Core Responsibilities
1. Request Routing
The gateway routes incoming requests to the appropriate backend service based on the path, headers, or other criteria.
Routing rules can be based on:
| Routing Criteria | Example |
|---|---|
| Path | /api/v1/products → Product Service |
| HTTP Method | GET /orders → Query Service, POST /orders → Command Service |
| Headers | X-Version: 2 → Product Service v2 |
| Query Parameters | ?beta=true → Beta Service |
| Client Type | Mobile User-Agent → Mobile-optimized endpoints |
2. Request Aggregation (Composition)
The gateway can aggregate multiple backend calls into a single response. This is sometimes called the API Composition pattern.
Benefits of aggregation:
- Reduces client round trips
- Moves complexity from client to server
- Enables parallel backend calls
- Provides consistent response format
3. Authentication and Authorization
The gateway handles authentication so individual services do not have to.
Common authentication patterns:
| Pattern | Description |
|---|---|
| Token Validation | Gateway validates JWT or OAuth tokens |
| Token Exchange | Gateway exchanges external token for internal token |
| Header Propagation | Gateway adds user context headers for downstream services |
| mTLS | Gateway establishes mutual TLS with services |
Request Flow:
4. Rate Limiting and Throttling
The gateway protects backend services from being overwhelmed.
Rate limiting strategies:
| Strategy | Description | Use Case |
|---|---|---|
| Fixed Window | N requests per minute | Simple rate limiting |
| Sliding Window | N requests in last 60 seconds | Smoother distribution |
| Token Bucket | Refill tokens at fixed rate | Allow bursts |
| Leaky Bucket | Process at constant rate | Smooth traffic |
| Per-User | Limits per user/API key | Fair usage |
| Per-Endpoint | Different limits per API | Protect expensive endpoints |
5. Protocol Translation
The gateway can translate between external and internal protocols.
This allows:
- External clients to use simple REST
- Internal services to use efficient protocols like gRPC
- Legacy services to remain unchanged
- Different teams to choose their preferred protocols
6. Response Transformation
The gateway can modify responses before sending them to clients.
Transformations include:
- Removing internal fields
- Converting naming conventions (snake_case to camelCase)
- Filtering based on client permissions
- Adding pagination metadata
- Versioning support
Gateway Architecture Patterns
Single Gateway
One gateway handles all traffic. Simple but can become a bottleneck.
Multiple Gateways
Different gateways for different client types. More complex but better suited for diverse requirements.
This approach is called the Backend for Frontend (BFF) pattern, which we will cover in the next chapter.
API Gateway Implementations
Kong
Open-source gateway built on Nginx. Extensible through plugins.
Key features:
- Plugin architecture (50+ plugins available)
- Multiple protocols (REST, gRPC, GraphQL, WebSocket)
- Admin API for configuration
- Kubernetes-native deployment option
- Enterprise features: developer portal, analytics
AWS API Gateway
Fully managed service from AWS.
Key features:
- Serverless (no infrastructure to manage)
- Integration with Lambda, ECS, EC2
- WebSocket API support
- Automatic scaling
- Usage plans and API keys
- Request/response transformation
NGINX
High-performance web server often used as an API Gateway.
Key features:
- Extremely high performance
- Flexible configuration
- Lua scripting for custom logic
- Load balancing built-in
- Can be extended with NGINX Plus
Envoy
Modern proxy designed for microservices.
Key features:
- Built-in observability
- Dynamic configuration via xDS APIs
- Advanced load balancing
- Circuit breaking and retries
- Foundation for service meshes (Istio)
Comparison
| Feature | Kong | AWS API Gateway | NGINX | Envoy |
|---|---|---|---|---|
| Deployment | Self-hosted or Cloud | Managed | Self-hosted | Self-hosted |
| Extensibility | Plugins (Lua) | Limited | Lua, modules | Filters (C++) |
| Protocol Support | HTTP, gRPC, WS | HTTP, WS | HTTP, TCP | HTTP, gRPC, TCP |
| Observability | Good | Basic | Basic | Excellent |
| Learning Curve | Moderate | Low | Moderate | High |
| Cost | Open source + Enterprise | Pay per request | Open source | Open source |
Design Considerations
Gateway as Single Point of Failure
The gateway is on the critical path for all requests. It must be highly available.
Strategies for high availability:
- Deploy multiple gateway instances
- Use a load balancer in front of gateways
- Deploy across availability zones
- Implement health checks and automatic failover
- Consider managed services that handle this automatically
Gateway Logic: Keep It Thin
The gateway should focus on routing and cross-cutting concerns, not business logic.
Good Gateway Responsibilities
- Route /api/orders/* to Order Service
- Validate JWT tokens
- Apply rate limits
- Transform snake_case to camelCase
Bad Gateway Responsibilities
- Calculate order totals
- Apply business validation rules
- Send notification emails
- Update database records
Latency Overhead
Every request goes through the gateway, adding latency.
Minimize overhead by:
- Keeping gateway logic simple
- Using efficient protocols (HTTP/2)
- Deploying gateway close to services
- Caching when appropriate
- Using connection pooling
Versioning
The gateway can help manage API versions.
Versioning strategies:
- URL Path: /api/v1/, /api/v2/
- Query Parameter: ?version=2
- Header: API-Version: 2
- Content Type: Accept: application/vnd.api+json;version=2
When to Use (and Not Use) an API Gateway
Use an API Gateway When:
| Scenario | Reason |
|---|---|
| External clients (mobile, web) | Reduce client complexity, optimize payloads |
| Multiple microservices | Centralize cross-cutting concerns |
| Third-party API consumers | API keys, rate limiting, usage tracking |
| Protocol translation needed | External REST to internal gRPC |
| Response aggregation needed | Multiple services for single screen |
Consider Alternatives When:
| Scenario | Alternative |
|---|---|
| Service-to-service calls | Direct communication or service mesh |
| Very simple architecture | Single service may not need a gateway |
| Extreme latency sensitivity | Direct calls save gateway overhead |
| Already using service mesh | Mesh provides similar features |
Summary
The API Gateway pattern provides a unified entry point for clients accessing microservices:
- The problem: Direct client-to-service communication leads to too many requests, tight coupling, duplicated concerns, and protocol mismatches.
- The solution: A gateway that handles routing, aggregation, authentication, rate limiting, and protocol translation.
- Core responsibilities: Request routing, response aggregation, authentication, rate limiting, protocol translation, and response transformation.
- Architecture patterns: Single gateway for simplicity, or multiple gateways for different client types.
- Implementations: Kong, AWS API Gateway, NGINX, Envoy, and others, each with different trade-offs.
- Design considerations: High availability, keeping logic thin, managing latency overhead, and API versioning.