Is Your Upstream My Downstream?

When working with microservices, people frequently refer to the communication between servers using the terms “upstream” or “downstream”. For example: “The upstream service reported a 400, so I had to pass a 500 on to my downstream client.” Frequently, you’ll hear people summarize the term by saying something like “upstream is towards the database, and downstream is towards the user”.

However, if you listen carefully to people in these conversations, you may begin to realize that these seemingly precise terms are not actually as precise as you thought they were. For example, a friend of mine recently wrote to me:

[To return data to my caller, my service] relies on two downstream web services for the Account and Reservation information.

Put another way “when my service receives a request, it then calls two other services to get the data it needs, and then returns a result.”

Why is this interesting? Note that in the first example the service being discussed was calling another service to get data, and the word “upstream” was used, while in my friend’s example, the service being discussed was calling another service and the word “downstream” was used.

I’ve spent years participating in conversations about network communication between microservices, and often people say things much more ambiguous than that. For example “Then the downstream returns 404”. Are you sure you know what the speaker meant? Naturally, you “know” what “upstream” and “downstream” mean, right? Yet, I’ve been in long meetings where the root-cause of a disagreement was simply that people understood these words differently.

But, it gets even better. I have been in conversations where a single colleague, over the course of one “paragraph,” has used “downstream” to mean opposite directions. And what term do you use when two “sibling” microservices (that is, where neither is closer or further away from either the database or the user) are talking with each other ?

The point here is that “upstream” and “downstream” are actually ambiguous terms.

Maybe this ambiguity should not be that much of a surprise. In an actual stream, water flows from one point to another. But in an HTTP interaction, first data flows in one direction and then (often as part of the same request) it flows in the opposite direction. It is more like ocean tides than the flow of a stream! I think part of the problem is that in the heat of a conversation, people end up focusing on the flow of data for whichever portion of the HTTP interaction that they are talking about, rather than the “absolute” direction of data going towards or from the user.

To make my conversations less ambiguous, I’ve ended up adopting another set of terms. In this case, I always refer to the services by their roles relative to my own service. When my service is communicating with another service, it is the supporting service of my service. Put another way, my service is relying on it to support its own ability to get its job done.

Similarly, when another service is relying on my service, that service is a client of my service.

Over time, I’ve found these terms to be much less ambiguous, and they have helped me hold more precise (and more efficient) conversations. Often this even helps force me to be more explicit when I am talking with others.

With these terms, I can now say things like:

• [To return data to my caller, my service] relies on two supporting web services for the Account and Reservation information.
• The response from my supporting service could be 403 sometimes, so I had to modify my readiness probe to account for that.
• The client service sent me a bad payload, so of course I returned a 400.
• I know it sounds crazy, but my supporting service would sometimes turn around and make a request back to me, making me its own supporting service. Clearly, we need to treat these requests very carefully, or we might have trouble getting results to the user within our SLA’s.

In summary, by speaking of the relative roles of microservices, rather than the direction of data flow (on a bi-directional data channel!) we can have more efficient conversations that also make it easier for those listening to the conversation to follow what is being said.

What to Read Next

I hope you enjoyed this article on communicating about microservices. Here are some other posts you might want to read next:

• Manage Feature Flags Efficiently in JavaScript
• The Art of Writing REST APIs
• Pac-Man Shows You the Benefits of Feature Flags

For more great content, follow us on YouTube and Twitter! You can also join the Split Community on Slack.