Introducing query messages for EventCatalog

;

Added in eventcatalog@2.10.0

In many distributed architectures, domains and services communicate through different types of messages, typically categorized as events, commands, and queries.

EventCatalog now includes support for documenting queries, allowing you to clearly outline which queries a service accepts and which it invokes. Queries are often seen in protocols such as HTTP and gRPC.

With the support of documenting queries, events and commands, you can now visually represent and document all the messages exchanged between services within your domains using EventCatalog.

; See a query example in the EventCatalog demo →

With the addition of query support, you can now provide your developers with deeper insights into how your services operate while also keeping track of the different message versions being used across your architecture.

Why document messages?

Documenting messages in a distributed architecture is crucial for several reasons:

• Clarity in Communication: Messages are the backbone of communication between services in distributed systems. By documenting them, you create a clear reference point for understanding how different services interact, what data is being exchanged, and how the system as a whole operates.

• Improved Developer Understanding: Detailed documentation of events, commands, and queries provides developers with a comprehensive view of the system's messaging flow. This helps them understand not only what messages are being sent and received but also the context and purpose of each message within the architecture.

• Version Control and Tracking: As architectures evolve, message formats and protocols may change. By documenting messages, teams can track which versions of messages are being used, ensuring compatibility across services and avoiding communication breakdowns due to version mismatches.

• Enhanced Collaboration: Documentation serves as a common language for developers, architects, and other stakeholders, facilitating better collaboration and alignment across teams. It helps ensure everyone has a unified understanding of how services communicate within the system.

In short, documenting messages helps maintain a well-organized, understandable, and reliable system, ensuring smooth communication between services and easier management as your architecture grows.

Getting started

To add a new query create a new folder within the /queries folder with an index.md file.

• /queries/{Query Name}/index.md
  • (example /queries/GetOrder/index.md)

New project structure support

EventCatalog now supports nested structures, so you can add your queries inside your services if you prefer. This is recommeded as your catalog grows. You can read more information in the documentation.

Add frontmatter and markdown to your query

---
# id of your query, used for slugs and references in EventCatalog.
id: GetOrder

# Display name of the query, rendered in EventCatalog
name: Get an order

# Version of the query
version: 0.0.1

# Short summary of your query
summary: |
  GET request (query) that requests the latest information for a given order.

# Optional owners, references teams or users
owners:
    - dboyne

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New query
      backgroundColor: blue
      textColor: blue
---

## Overview

The `GetOrder` message is a query used to retrieve detailed information about a specific order, identified by its `orderId`. It provides information such as the order status (e.g., pending, completed, shipped), the items within the order, billing and shipping details, payment information, and the order's total amount. This query is commonly used by systems managing order processing, customer service, or order tracking functionalities.

This query can be applied in e-commerce systems, marketplaces, or any platform where users and systems need real-time order data for tracking, auditing, or managing customer purchases.

<NodeGraph />

Once you start your Catalog and view your query you will be presented with a page that looks like this.

;

Queries also support versioning, custom components and much more. You can read the documentation to get started or see the example on GitHub.

Summary

EventCatalog now includes support for documenting queries, allowing you to capture any queries your service accepts or sends. This feature enhances the ability to track and visualize the full range of messages within your architecture.

Queries come with support for schemas, versioning, and custom components, offering flexibility in how you document them. However, including queries in your catalog is entirely optional and not a requirement.

If you want to get started you can read the query guide or see queries in the EventCatalog demo.