Repository navigation
MicroService Messaging Patterns Commands
On the previous pages, we focused primarily on the design and behavior of a single MicroService. In doing so, we also introduced how MicroServices integrate and interact with each other. On this and the following pages, we will focus specifically on all common Messaging Patterns that are used in Service-Oriented, Event-Driven Architectures. We will start with message exchange patterns that can be used for sending and receiving Commands.
The most common source of Commands are clients (i.e. user interfaces). When a client sends a Command to a server (which is typically the back-end of its own service - clients are not encouraged to send Commands to other services directly), it usually sends it synchronously. Sending a Command synchronously means that the sender - the client in this case - awaits the result of the operation, which can either be an OK-response (Command has been processed successfully) or an error-response (which can be caused by a functional or technical error). Remark that the response that is returned by the service can only contain information about the outcome of the operation; it should not contain any entities, identifiers or any other business data.
This immediately brings us to the main advantage of synchronous communication: since the sender is informed directly about the outcome of the operation, it can act upon that outcome instantly. This is particularly useful for clients that may want to inform the user about the result of their action (e.g. saving some changes) by showing an appropriate message on the screen:

By default, clients send their Commands synchronously to the server through an API.
To communicate with a service, clients are connected to an api of that service through a proxy defined in the contract of that service. A very common solution nowadays is to deploy the api to a remote server and let the client(s) configure the proxy such that it connects and talks to the remote api over a network (e.g. over the internet). The most popular solution in our web-based world of today is, in fact, to expose the back-end of a service through a RESTful API and use the http-protocol to send and receive messages from the (remote) service.
Note, however, that none of this is actually required. Native applications and/or standalone clients may be installed on the same machine as the (back-end of the) service they are connected to and may even be running in the same process. In such case, the api may be nothing more than a simple interface with methods that are invoked directly by the client:

The components of a service could all be deployed as a single application (left) or deployed over multiple servers (right). These deployment choices, however, don't affect the Messaging Patterns and Principles.
Another advantage of synchronous communication is that it is conceptually very easy to design, understand and implement: just send a Command, await the result and then act accordingly (e.g. update the user interface). For these reasons, synchronous communication is the default style of communication between a client and a server.
At this point, it is probably worth noting that when we talk about synchronous communication, we are explicitly not talking about blocking threads or freezing the UI while a Command is still being processed. What we mean by synchronous communication is that a client uses a specific request/response protocol to send a Command to a service and that service then returns that response as soon as its done processing that Command. How a client actually sends the Command or awaits the result (e.g. using async/await in C#) is irrelevant here.
A drawback of synchronous communication is, however, that it requires the api to be available. In other words: the sender is run-time dependent on the service that exposes the api. If the api is not available (i.e. not responding in a timely fashion), then the client can no longer offer the features that rely on that api and may even stop functioning completely (especially if the client is not build to deal with that situation).
For native and/or standalone clients that only have a local connection to the api (i.e. are at least installed on the same machine), availability is not really a problem, but when the connection runs over a network, reliability issues of that network may cause temporal availability problems, especially if the service is running in a data center on the other side of the world. In addition, a service may become temporarily unavailable because it is being updated or the server it is running on goes down for some reason. Note that, since clients are usually part of the same service as the back-end they are connected to, this run-time dependency does not necessarily violate the desired run-time independence between services, but it's still a practical issue to cope with. This run-time dependency is, however, the main reason why you should avoid synchronous communication between two different services as much as possible. The only viable reason to do so would be if the receiving service is not under your control and you have no choice but to connect to its api to send a Command:

Using synchronous communication between services is discouraged because it creates a run-time dependency between them. In some cases, you may not have a choice, though.
Another drawback of synchronous communication between client and server is that a user interface can become unresponsive if the Commands take a very long time to process. This is, of course, precisely because the client awaits the result of the operation: if that operation takes a while to complete, users may experience long delays in the UI. Moreover, if a service is really busy and/or overloaded, processing times may start to rise to unacceptable levels, hurting responsiveness and the overall experience of the user. In extreme cases, Commands may even begin to timeout, as the time to process them starts to exceed the configured timeout period (on the client's side), which is typically a minute or so. As the user interface shows the error to the user, users may react by ferociously retrying to perform the desired action (e.g. by clicking a save-button), unintentionally making matters even worse because the service will then be bombarded with even more Commands. As a result, even though the server may actually still be running in the background, the service has effectively become unavailable and may even cause the client to crash.

When an api is overloaded, operations can start to experience timeouts.
A well-designed user interface can mitigate these problems somewhat by not crashing or freezing when an api becomes unresponsive or unavailable. A client can, for example, use a circuit-breaker to detect early that an api has become slow or unavailable and (temporarily) disable functions in the user interface until the service comes back up again. Similarly, a user-friendly client does not freeze or block the UI while it's awaiting the result of one or more Commands.
On the server-side, any anticipated performance problems caused by heavy load can be mitigated or solved by scaling out and/or scaling up the infrastructure on which the api has been deployed. When scaling out, you essentially increase the number of servers that host your api behind a certain load-balancer so that the load of incoming Commands can be divided over more instances, resulting in faster processing and response times. When scaling up, you basically move your api to a server with more processing power (cpu, memory, etc), which also results in faster processing and response times. Both methods have pro's and con's related to performance and pricing, and they can also be combined if desired, but an in-depth discussion on this topic is outside the scope of this chapter.

Server performance can be increased by deploying more instances (scale-out) or by increasing the capabilities of each server (scale-up).
Yet another way to avoid any problems with availability and responsiveness of the api is to move away from synchronous communication entirely and to send Commands asynchronously to the server instead. With asynchronous communication, also known as fire-and-forget, a client or neighboring service just sends the Command (fire) to the server but then does not await the result of the operation (forget). In this scenario, the sender simply relies on the fact that the server will eventually process that Command.
The reason why asynchronous communication can solve the performance problems spoken of earlier is because in this case a queue is placed between the sender and the receiver. When a Command is sent asynchronously, the sender effectively just adds the Command to this queue and then forgets about it. On the receiving side of the queue, the server will pick these Commands off the queue one by one and processes them at a rate it can handle. This design is commonly known as the producer-consumer pattern and is not limited to only a single sender (producer) or receiver (consumer):

By introducing a queue between sender and receiver, Commands can be handled asynchronously, effectively removing the run-time dependency between them.
Let's, in fact, assume that there are several senders connected to a single server instance through this queue, and that at busy times these senders are all sending lots of Commands to the server. If the senders were all connecting to the server (i.e an api) directly, the server might choke and start responding slowly or even become completely unavailable as explained earlier. What now happens instead is that the queue starts filling up as senders are adding Commands to it faster than the server can remove and process them. The senders, however, remain responsive because they are no longer stalled by long processing delays. The server may, in fact, go down entirely for short periods of time without any sender ever noticing, effectively removing the run-time dependency between the sender and the receiver.
This behavior where a consumer (i.e. the server) can handle and process the Commands at its own steady rate, regardless of how fast the producers add these Commands to the queue is known as throttling. Besides the benefits related to the responsiveness and availability of the UI (in case the sender is a client), this design may even prevent you from having to scale-up or scale-out your servers to improve performance on the back-end - avoiding the additional costs and complexity that comes with it - as long as the server(s) you are using can handle the average load. In other words: the queue is allowed to grow in size during peak-load times, as long as the server is able to catch up and empty the queue again in quiet times. If you notice, however, that the queue keeps growing in size over longer periods of time, you may combine the queuing solution with more servers or faster servers to increase the rate at which Commands can be processed and picked off from the queue:

When scaling out, multiple servers can be connected to the command-queue to increase the rate at which Commands are handled.
So if asynchronous communication provides all these benefits compared to synchronous communication, why not always use it? Well, first of all, because it increases the complexity of your solution, and you should only introduce complexity if you really need it. Secondly, what we have ignored up to this point is that in a fire-and-forget scenario, the client simply assumes that the Command will eventually be processed successfully. This is important, because, as we know by now, Commands may fail for several reasons: authorization can fail, validation can fail, business rules can be violated, etc. As such, clients that send Commands asynchronously to a server essentially take a risk: what if the Command fails?
Generally speaking, the solution to this problem is to design your system such that Commands that are sent asynchronously almost never fail. Needless to say, the client always has to make sure that it sends each Command along with the proper credentials and values so that the authorization and validation steps are pretty much guaranteed to succeed. To minimize the chance on any business rule violations, however, you have to do something different: instead of forcing business rules upon a Command and fail if one of them is violated, you can also simply implement two or more separate happy flow paths that will publish Events that are appropriate to path taken.
To illustrate how this works, let's go back to the example where a PlaceOrderCommand may fail if the account of the user that is attempting to place that order has been blocked. Instead of throwing a business rule violation exception and return an error to the sender, we could also just publish an OrderPlacementFailedEvent containing the order details and reasons for not placing that order. This way, the Command is technically processed successfully, and thus removed from the queue, but the business result is the same as before: the order was not placed because blocked accounts are not allowed to do so.

Business rules can sometimes be implemented as alternate flows without returning errors.
Implementing your business logic this way has the added benefit that you now have another Event that services can respond to. Instead of just notifying the sender of the problem (Command denied), you can actually treat such failures as legitimate, foreseeable business scenarios that you may want to act upon. For example, you could now implement a service that handles the OrderPlacementFailedEvent by sending an e-mail to the user notifying him of the fact that his order was denied because his account has been blocked.
Some might say that you should always attempt to design your workflow and avoid throwing business rule violation exceptions if you can - not just for asynchronous processing. It's hard to argue with that given all the benefits of this design, but in some cases (e.g. simple save-operations) it may also complicate design, so I suggest you at least consider it but don't feel forced to do it.
In the previous paragraphs, we explained that clients and services can send Commands synchronously through an api or asynchronously by adding Commands to a (worker-)queue of the service. When implementing an api, especially if its a remote api like a RESTful api, the Commands are sent by a local proxy. The proxy then makes sure that the Command is properly serialized and send to the correct endpoint of the api and that the response of the api is properly received and deserialized. As explained on the previous page, the api itself is actually part of the Endpoint Layer of the service, which will authorize and validate the Command before it dispatches it to the Data Access Layer for further processing.
However, in the case of asynchronously sending a Command, if we allow clients and other services to add Commands to a queue directly, the Endpoint Layer can only authorize and validate the Commands as soon as it picks them off the queue - so after they've been added to the queue. Since authorization and validation are meant to deny Commands quickly, this is not a desirable situation: we would rather perform these steps before Commands are added to the queue. This way, we ensure that every Command in the queue has been authorized and validated, protecting the queue from pollution messages, and that the sender is notified if his Command was refused. So what we propose is to implement a hybrid solution where Commands are always send to an api, but that those Commands that are meant to be processed asynchronously are forwarded to the service's worker-queue after they have been authorized and validated:

Combining a thin api with a queue behind it can provide a good balance between performance, reliability & maintainability.
The added benefit of this solution is that clients and other services can always use a simple proxy to send Commands to your service - whether they are being processed synchronously or asynchronously is up to the service's implementation and invisible to the sender. Moreover, the fact that this solution hides the queue completely from the sender aligns with proper design principles, because the queue itself is just an implementation detail (i.e. an infrastructural component used by the service), which you don't want to share with other services.
Looking at this hybrid solution you may be asking yourself: but what about run-time independence, then? Wasn't one of the main reasons to use a queue to make sure that even when a service goes down, Commands can still be sent asynchronously to that service? And yes, to be perfectly honest, you would be right: introducing this thin api between a sender and the queue does technically reintroduce a run-time dependency between the sender and the receiver, because if the api goes down, Commands can no longer be sent to the service.
However, that being said, the hybrid solution is a nice trade-off between clean design, run-time (in)dependence and performance considerations. Moreover, since we have essentially split the Endpoint Layer into a slice that only does authorization and validation, and another that actually processes the Commands, you could, in theory, deploy both parts to different servers and apply different scaling strategies to increase the availability of the former (i.e. by scaling out) and save costs on the latter:

Availability of the API used in the hybrid solution can be improved by scaling out the parts that perform the authorization and validation.