Repository navigation
MicroService Contract & Behavior
On the previous page we introduced the service contract as one of the main components of a service. On this page, we are going to dive deeper into the contract and explain what it typically contains and how it is implemented. We will then describe which types of messages exist and how services typically process them.
The contract of a service is a set of libraries that contain all messages that can either be sent or received by that service. There are basically four types of messages that can be defined inside a contract:
- Commands, which represent a request to perform a specific operation (i.e. execute business logic/mutate data).
- Events, which represent a change or fact of interest in the system (i.e. an operation that has been performed, a timer that has gone off, etc).
-
Queries, which are read-operations on a service that are actually represented by Request/Response-message pairs where...
- the Request-message contains the parameters of the Query, and...
- the Response-message contains the result of the Query.
As we will discuss later in more detail, every request-message that is consumed by a service (i.e. the Commands and Request-messages of a Query) needs to be validated by the service before it will process it. When a message is validated, the service basically checks whether or not the message contains all the required data and whether or not that data is valid (i.e. contains sensible values, such as an age that is not negative or a start- and end-date forming a valid period).
Message validation is typically implemented by declaring a set of constraints on the properties of a message. It is encouraged to include all validation-constraints into the service contract along with the messages, because the two are intimately related. Moreover, by putting the validation-constraints into the same library, consumers of your contract can pre-validate each message (e.g. a Command) before they send it to your service.
Note that more often than not, validation-constraints are declared on the properties of a message by validation-attributes, which automatically binds these constraints to the messages.
Aside from the messages and their validation-constraints, a service contract can also contain interfaces, proxies, configuration-files and other components that are helpful for clients and other services to integrate with your service. Proxies, for example, are typically used to connect to your service's api, which enables you to execute Commands and Queries. Events, on the other hand, are often published and delivered through a ServiceBus or ESB, as thus often used a different technology-stack to transfer these messages from one service to another. As such, a service contract is best divided into at least two separate libraries:
-
Contract.Api
- Contains all Commands and Queries (i.e. Request- and Response-messages) that are supported by the service.
- Contains all validation-constraints.
- Contains all interfaces and proxies to integrate with your service's api.
- Optionally contains other files and components, such as configuration-files, documentation, etc.
-
Contract.ServiceBus
- Contains all Events that are published by the service.
- Contains all clients and/or factories that enable you to receive these Events from the service-bus.
- Optionally contains other files and components, such as configuration-files, documentation, etc.

Commands are messages that represent a request to a service to perform a specific (business) operation. These operations usually mutate some data and save those changes back to a database (or to whatever storage is used). The code that performs those changes to the data is called the business logic of a service. (Along the same lines, the rules that serve to check whether or not the mutations are allowed are typically called the business rules).
The naming convention for Commands is Verb-Noun-Command (without the dashes). Typical examples are:
- PlaceOrderCommand
- RegisterUserCommand
- StartChatCommand
In an event-driven system, if a Command is processed successfully, any changes in the system are not only persisted back to the data-store of that service, but they are also published as a set of Events. Each event then typically reflects one specific change or mutation of a specific entity in the system (e.g. OrderPlacedEvent), but it can also represent other events of interest to the business that do not necessarily reflect a data-change (e.g. OrderConfirmationEmailSent).
If we look at a service as a black box, then we can depict this behavior as follows:

Although it is a lot less common, services can also send out new Commands to other services when processing a Command. The reason that this is a lot less common is that messages (either Commands or Events) can only be sent out after the service has committed to its own changes. As we will discuss next, however, the receiving service may fail to process the new Command(s), which, if not taken care of properly, can result in problems in consistency in the system. One thing to mitigate this problem is to implement the business process in such way that is either highly unlikely that the new Commands are not processed as expected, or that failure does not result in such problems (e.g. when the Command represents an optional step in the business process and it allowed to fail). That being said, however, it is typically better to let services communicate through Events instead of through Commands.
There are a couple of reasons why a service may fail to process a Command. The most common reasons are when...
- the sender or user is not authorized to execute the command,
- the command self is invalid (e.g. required fields are missing) or
- a business rule was violated while processing the command.
If a services fails to process a Command for any such reason, the internal transaction is aborted, no mutations are performed and the service will return an appropriate error-response to the sender of the Command. Needless to say, the service will also not publish any Events nor send out any new Commands to other services. This can be depicted as follows:

If, for example a Command was sent by a client (e.g. website) and processed by a web api, then the api will return a 400 (Bad Request) or more specific response in the 4xx-range so that the client can handle this error by showing the appropriate message to the user. If, on the other hand, the Command was delivered by a service bus, the service bus typically places the Command back into its outbox and may attempt to redeliver the Command later.
Events are messages that represent a specific change, fact or other occurrence of interest in the system. As explained previously, Events are most commonly used to represent the outcome of a business operation, reflecting the changes made in the system. For example, while processing a PlaceOrderCommand, the service may publish an OrderPlacedEvent as a result, indicating a new order has been placed (i.e. added to the system).
The naming convention for Events is Noun-Verb-Command in passed tense, (without the dashes). Typical examples are:
- OrderPlacedEvent
- UserRegisteredEvent
- ChatStartedEvent
To a certain extent, processing an Event is very similar to processing a Command: both trigger a specific piece of business logic and may produce a set of Events and Commands as output. This mechanism, where Events published by one service can trigger changes in another service which then produces more Events, etc. etc. is what makes Event-Driven Systems so dynamic and loosely-coupled. Suppose, for example, that an OrderService publishes the OrderPlacedEvent, then an EmailService may handle this event by sending an e-mail to the customer. The operation may produce yet another event, such as the an OrderConfirmationEmailSentEvent, which may be handled by yet another service:

Although both Commands and Events can trigger operations and changes in the system, there is, however, one major difference between processing Commands and Events: Commands can fail because of failed authorization, validation or business rule violation as described earlier. Events, on the other hand, cannot fail in such a way. This is because Commands represent a request, and requests can be denied, whereas Events represent a fact or change in the system, and as we know, facts cannot be denied. In other words, services never return a functional error when processing an Event*. What services can do, however, is choose to ignore an event if circumstances no longer require to make further changes in the system. In short, a service can either perform certain operations and publish new Events as a result, or just do nothing when processing an Event:

*There is only one situation in which services can return a functional error while processing an Event, and that is when a concurrency conflict is detected when saving the changes that were triggered by that Event. Concurrency conflicts can, however, often be solved by simply redelivering the Event to the service until it finally succeeds. This is discussed in more detail on the next page.
Queries represent read-operations of a service. Where Commands and Events may trigger business operations and changes in a system, queries just retrieve data and are not allowed to make any changes in the system. Note that when we talk about changes in the system, we typically mean mutating the business data that is being managed and protected by our business rules - writing to logs, tracing the flow of operations or profiling an application is always allowed.
When processing a Query, a service actually processes the Request of that Query and, if all goes right, simply returns the Response:

Since no mutations are performed, a service will not publish any Events when it executes a Query. (Again, an exception is made for Events that represent meta-data meant for monitoring the system.)
Queries can, however, fail (i.e. be denied) like Commands can, because just as with Commands they represent a request. The only difference with Commands is that Queries do not execute business logic, so they cannot fail for violating a business rule, but only for the following reasons:
- The sender or user is not authorized to execute the query, or
- The request of the query is not valid.

Another difference between Commands and Queries is that Queries can only be executed synchronously, whereas Commands can be executed synchronously or asynchronously, depending on context and preference. The reason that Queries can only be executed synchronously is that the sender of the Request is expecting an immediate Response, and so the sender must wait for the Query to complete and receive that response from the service.
The seasoned engineer may argue that for long-running Queries, a service may actually execute a Query asynchronously by preparing or building a Response and then publish that Response on a service-bus, for example. This would allow the sender of the Request to simply receive the Response at the moment it is ready instead of having to actively wait for it. Although such flow might, in some situations, be a viable option, I would argue that this design can no longer be called a Query but is rather a specific Command/Event-scenario.
So far, we've talked about the possibility that requests (i.e. Command and Queries) may fail because authorization, validation or business rule failed. When a service denies a request for such reason, we are talking about a functional error. Functional errors are, generally speaking, errors that are returned by design. This means that these errors are actually part of the functional specification of a service.
However, there are also many things that can go wrong while processing any type of message that are not part of the functional specification. Examples of such errors are:
- Network failures, preventing your service to connect to its database, publish its events or query other services.
- Insufficient memory (either in RAM or on disk).
- Memory or disk failures.
- Problems related to the operating system, resulting in a sudden shutdown of our service.
These kinds of errors are known as technical errors, and they can basically occur at any place and at any time in your system. Since we, as application developers, have no control over them, the only thing we can do is handle them as gracefully as possible. This implies that, when a technical error occurs while a message is being processed, a service must make sure it protects the integrity of its data (e.g. by rolling back a running transaction), log the error details and return an appropriate error to the sender of that message, if possible. For web api's, the appropriate error code to return is 500 (Internal Server Error) or a more specific code in the 5xx-range, if it applies.
When the sender of a message - which can be a client, service or service bus - receives back a technical error code from a service, it may choose to re-dispatch that message a few times until the operation succeeds. The reason why this may actually work is that some unexpected problems, such as glitches in a network connection or temporary unavailability of a resource, can be very short-lived and solved within the next second or so.
Unfortunately, some problems are more persistent and may actually require an administrator (crashed disk) or developer (bug) to fix. In such cases, consecutive retry attempts will then also fail, which is why retry-policies should be configured to retry only a fixed number of times - otherwise your are only wasting system resources. A better way to handle this situation, if you don't want your message to be lost, is to persist the message and retry once the problem has been solved. This strategy is actually used by most service buss, which will put your message(s) into a dead-letter queue if the service keeps returning errors when trying to process it, giving you the opportunity to move back those messages to the main processing queue once the service is fixed.
This concludes our analysis of a MicroService's behavior when looking at it as a black box, which paves the way to go looking at its internal structure.