Understanding Upstream and Downstream in API Gateway

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

Request Volume (RPS)
Authentication failures
Latency perceived by the client
Error rate (4xx and 5xx responses)

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

Request/response format
Changes in service structure
Versioning to avoid breaking downstream clients

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:

UpstreamPathTemplate → path that the client (downstream) calls
DownstreamPathTemplate → path that the gateway calls internally (upstream)

{
  "Routes": [
    {
      "UpstreamPathTemplate": "/api/orders",
      "DownstreamPathTemplate": "/v1/order-service/orders",
      "DownstreamHostAndPorts": [
        { "Host": "localhost", "Port": 5001 }
      ]
    }
  ]
}

Client calls → /api/orders → downstream
Gateway forwards internally → /v1/order-service/orders → upstream

AWS API Gateway

Downstream: Client → API Gateway endpoint
Upstream: API Gateway → Lambda / ECS / HTTP service / ALB

AWS handles upstream integrations using:

Integration Request mapping
VTL templates
Lambda proxy integration
Stage variables for versioning

Kong / NGINX

Kong defines:

Route (downstream): paths, methods exposed to clients
Service (upstream): actual backend service URL

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?

Wrong routing
Authentication failures
Services unreachable
Increased latency
Unexpected 4xx/5xx errors

Q4. What security layers apply to downstream only?

JWT/Token validation
API Keys
Throttling
CORS
These do NOT apply to upstream services.

Q5. How does the gateway handle upstream service failures?

Retry
Fallback responses
Circuit breaker
Cached responses
Return standardized 5xx error to client

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.