Web Services 101: The client is downstream, the service is upstream

Sometimes I read a conversation between two devs online or I overhear one while filling up my water bottle that goes something like this:

Dev 1:

"I think there's something wrong with the downstream service. It keeps timing out so we keep sending 500's to our clients and it's becoming a big issue."

Dev 2:

"That service actually talks to like four others to return the response. I bet its some issue even further downstream."

This usage of "downstream" is actually wrong, and this is not a subjective observation.

What does up/downstream actually mean?

In web services, upstream and downstream are actually defined by the HTTP specification as follows:

upstream/downstream

Upstream and downstream describe the flow of a message: all messages flow from upstream to downstream.

In other words, in any HTTP interaction, the requesting service is downstream. The service responding is upstream.

This isn't just a random definition thrown into the opening portion of the specification and then ignored thereafter, either. You will find this specific usage of up/downstream throughout the specification. Consider the definition of a 504 Gateway Timeout response for example:

The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request.

You will also find the same usage in documentation for things like nginx.

To visualize this, consider a series of service calls initiated by some external client, as follows:

client -> service A -> service B -> service C

The above is the request flow, but the response flow is:

client <- service A <- service B <- service C

The response flow is the flow that is the basis for "upstream" and "downstream" in web services.

For another take on this, check out this old Stack Overflow question.

Hope it helps!