Upstream vs Downstream Services

December 11, 2023

From RFC 2616 Section 1.3:

upstream/downstream Upstream and downstream describe the flow of a message: all messages flow from upstream to downstream.,upstream/downstream,-Upstream%20and%20downstream

Is it “upstream” or “downstream”?

Here’s a request diagram of your web stack:

web stack diagram

The users starts downstream.

The MySQL is the most upstream service.

For example, in this request diagram, we could say:

  • The REST API is upstream of nginx
  • The BFF Service is downstream of MySQL

“You’re wrong, it depends on which way you look at it”

Upstream vs downstream can indeed be flipped depending on if you’re talking about a request or a response. But nobody ever does that and just says “downstream” or “upstream” without the added context of a direction. So for places where we’re picking a word without the directional context, “upstream” seems correct given usage of it in other places (e.g. nginx makes you configure “upstreams” referring to the proxy target, a git upstream etc)

Cool! I’ll tell all my friends and family and use “upstream/downstream” correctly in my RFCs!


Let’s be honest, “upstream vs downstream” is super easy to get mixed up and can be confusing terminology as a result.

So - for the sake of clarity, consider using non-ambiguous english - e.g. “service we’re calling” or “service that called us”.


Prior art

Discuss on TwitterEdit on GitHub