When you dive into event-driven architecture you will see one of the main benefits is “loosely coupled” services. In fact many people will say “producers should not know about consumers”, this is technically true… but overlooked.

Technically our producers should not know about consumers but operationally as humans we do. Common questions come up when building EDA applications over time:

1. What events/messages is this service producing?
2. What events/messages can I consume from this service?
3. What is the format of these events/messages?
4. What schema version do I use?
5. Who is producing what?
6. Who is consuming what?

These are common questions that will arise when building EDA applications.

Here are three areas that I consider that can help:

Using README files

Simple and cheap. If you want to document your schema, or what your service is publishing or subscribing too, maybe readme files can help? Anything is better than nothing. (maybe you think nothing is OK, but as you scale your app high chance you might need some form of discovery)

AsyncAPI

AsyncAPI is an open source specification for defining asynchronous APIS. The community has been growing over the past few years and many large organistions using it to help them define and write standards for producers and consumers. Community has a wide range of tools to help with integrating and documentation too.

EventCatalog

I’m of course biased here, this is my own open source project called EventCatalog. I designed this to help people document their EDA applications, powered by markdown files and custom plugins. You can connect any system you want to EventCatalog and generate markdown files. This web interface gives your team a new visual way to navigate producers, consumers and domains. See example in action here.

Extra resources

• AsyncAPI - Open-Source tools to easily build and maintain your event-driven architecture. All powered by the AsyncAPI specification, the industry standard for defining asynchronous APIs.
• EventCatalog - EventCatalog is an Open Source project that helps you document your events, services and domains.