What is the difference between Document, Event and Command?

What should you use when designing communication between services? When to use Document, Event, and when Command? What are the differences and similarities between them?

 
In this post, I will share a few things that may help you make a good decision.

What are Document, Event, and Command?

Let's take a look at the following JSON (I skipped information like ids, timestamps, etc.):

{
  "productId": "1234567890",
  "category": "book",
  "title": "Software Mistakes and Tradeoffs",
  "ISBN": "9781617299209",
  "authors": [
    "Tomasz Lelek",
    "Jon Skeet"
  ],
  "price": {
    "value": "32.99",
    "currency": "USD"
  },
  "pages": 416
}

It would be difficult to say if that is a Document, Event, or Command. Neither the structure nor the data do not help. All three types of messages may carry the same information and have the same structure. What differentiates them is the intention. And this is the information you can add to your communication by using the correct type of message.

What are Document, Event, and Command?

• Command - a message that expresses we want particular action to happen. 
  

• Event - a message that informs that something just happened.
  

• Document - a message to share a set of information with other services.

If we look at the JSON once again, but this time we name it, we receive more information, e.g.:

• ModifyProduct - this is a command. It tells us we want to change the product, and we expect the values of its field will be the same as sent in the message once the action is completed successfully. We also know the change did not happen yet.
  
  

• ProductModified - this is an event. It tells us the product was changed. Data carried out by the event reflect the current state of our product.
  
  

• Product - this is a document. This type of message tells us nothing about the intention. It can be used both as an input (so maybe we want to modify a given product) or as an output (e.g. product that was modified, created, or the one we were looking for). 

How are they used in communication?

There are some more differences between Document, Event, and Command:

• Command - when we use commands, we know there is a service that will get triggered by our command to do what is expected. We know what will happen if the message will be processed successfully. We also know only one service will react. 
  
  

• Event - when we use events, we want to let others know the job was done. We usually do not care who (if anyone) will consume the event. The event can be consumed by zero, one, or many consumers. We don't know what services do once they consume the event.
  
  

• Document - we use documents when we want to keep our API simple e.g. when we create CRUD REST controllers to manage the resources of our software. We don't need to reveal any intentions.

Where to use them?

When you create communication between services you own it is a good idea to use both Commands and Events. Thanks to this approach, the communication itself gives you additional information about the intention and behavior.

One situation when documents are great is designing entry points to the product we build, e.g. API for UI applications or open API exposed for others to use. Another scenario is when we must publish a result of internal processing so that it can be consumed by other applications.

Conclusion

Even though Document, Event, and Command may look (almost) the same, you should remember each type of message gives you additional information. When you design the communication between services, it is worth considering all the differences. It will make your APIs more meaningful and informative.