When building microservices, one of the most confusing terms developers encounter is the Distinction Between Upstream and Downstream traffic in an API Gateway. Understanding these two directions of communication is essential for designing routing, security, and performance.
What You Will Learn
The complete API request flow from client → gateway → microservice → client
How API Gateways interact with clients (Downstream) and backend services (Upstream)
Difference between Downstream and Upstream.
How major gateways—AWS API Gateway, Kong, NGINX, and Ocelot—implement upstream/downstream routing
Common Interview Questions and Answers.
Understanding the Request Flow
Before learning upstream and downstream, we must clearly understand what happens when a client calls an API.
Step-by-step Flow
A client (mobile, web, partner app, Postman) sends a request.
The request reaches the API Gateway (reverse proxy).
Gateway applies:
Authentication
Throttling/Rate Limits
Request validation
Gateway routes the request to the correct microservice.
Microservice processes it and returns a response.
Gateway transforms or standardizes the response.
Client receives the final output.
Visual Model
Client → API Gateway → Microservices → API Gateway → Client
The direction between client → gateway is called downstream.
The direction between gateway → services is called upstream.
How API Gateway Sits Between Clients and Microservices
API Gateway is a protective and intelligent layer that:
Shields microservices from direct exposure
Provides a single entry point
Handles cross-cutting concerns (auth, rate limits, logging)
Manages traffic flow to backend services
Offloads client communication complexity
It becomes the “traffic controller” for your microservices ecosystem.
What is Downstream?
Downstream refers to clients sending requests into the gateway. ****These are the consumers calling your APIs.
Examples of Downstream Consumers
Mobile apps (Android/iOS)
Web apps (React/Angular)
External third-party integrations
Postman, curl, Swagger UI
IoT devices
Downstream Concerns
The gateway manages multiple responsibilities before passing the request to services:
Authentication / Authorization
Rate Limiting & Throttling
Input Validation
Logging & Monitoring
Request Transformation
API key checks / JWT verification
Key Downstream Metrics
Downstream ensures safe and smooth communication from consumers into the system.
What is Upstream?
Upstream refers to the communication between the gateway and the backend services.
These are the services that perform the actual business logic.
Examples of Upstream Services
Order Service
Payment Service
User Service
Inventory Service
Notification Service
Upstream Concerns
The gateway handles internal orchestration tasks such as:
Routing to correct microservice
Retries when upstream fails
Circuit breakers
Timeouts
Load balancing
Caching
Versioning (v1/v2/v3 service contracts)
API Contract and Versioning
Upstream ensures stable and resilient communication within the system.
Upstream vs Downstream
| Topic | Downstream | Upstream |
|---|
| Direction | Client → Gateway | Gateway → Services |
| Who Sends Requests? | Consumers | API Gateway |
| Security Applied | Authentication, API keys, JWT | Service-to-service authentication |
| Concerns | Throttling, validation, access control | Routing, retries, load balancing |
| Common Errors | 4xx (client errors) | 5xx (service failures) |
Example GET Flow
Client → Gateway → ProductService → Gateway → Client
Example POST Flow
Client → Gateway → OrderService → Gateway → Client
Downstream ensures safe entry.
Upstream ensures correct execution.
Real-World Examples (AWS / Kong / NGINX / Ocelot)
How different gateways define upstream and downstream paths.
Ocelot Example (ASP.NET Core)
Ocelot uses:
{
"Routes": [
{
"UpstreamPathTemplate": "/api/orders",
"DownstreamPathTemplate": "/v1/order-service/orders",
"DownstreamHostAndPorts": [
{ "Host": "localhost", "Port": 5001 }
]
}
]
}
AWS API Gateway
AWS handles upstream integrations using:
Kong / NGINX
Kong defines:
Example:
Route: /customers (downstream)
Service URL: <http://customer-service:8080> (upstream)
Downstream vs Upstream Policies
| Layer | Who Applies Policies | Examples |
|---|
| Downstream Policies | Gateway to Client | Auth, rate limit, IP allow/deny |
| Upstream Policies | Gateway to Backend | Retry, timeout, circuit breaker |
Common Interview Questions and Answers
Q1. Explain upstream vs downstream in simple terms.
Downstream is when clients call the gateway.
Upstream is when gateway calls backend services.
Q2. Why do we need both mappings?
Because the URL clients use may not match internal microservice URLs.
Gateways help hide internal architecture and provide security.
Q3. What problems arise if upstream or downstream is misconfigured?
Q4. What security layers apply to downstream only?
Q5. How does the gateway handle upstream service failures?
Conclusion
Understanding Upstream and Downstream traffic is essential for designing secure, scalable, and resilient API architectures. The API Gateway serves as the bridge between clients and microservices, applying the right rules at the right stage—validation and security on the downstream side, and routing them on the upstream side.
I hope this article helped you understanding of upstream vs downstream in API Gateway, and how these concepts apply in real-world microservice systems.