8 posts tagged with "EventCatalog"

Last week we launched the new AsyncAPI Plugin and today I'm happy to share we have now launched our next integration: OpenAPI Plugin.

The EventCatalog OpenAPI plugin connects your OpenAPI files to EventCatalog and automates the hydration of your catalog, versioning and schema management.

What is OpenAPI?​

The OpenAPI specification is a widely-adopted standard for defining and describing RESTful APIs in a structured, machine-readable format. It provides a way to document APIs, including the endpoints, parameters, request and response formats, authentication methods, and more, making it easier for both humans and machines to understand and interact with the API.

Why integration with EventCatalog​

For many years people have been using OpenAPI specifications to help document their APIS.

Integrating with OpenAPI specifications allows users of EventCatalog to generate their services, map them to domains, visually see there architecture, parameters, responses and payloads.

Our vision with EventCatalog is to help companies manage event-driven architecture discoverability and it's complexity through documentation and integration tools. Part of this vision is to automate some of this complexity and documentation for you. That's why we have integrated with OpenAPI.

How the plugin works​

EventCatalog can be powered by generators. Generators can be used to automate the creation of your EventCatalog.

The OpenAPI generator takes your OpenAPI files and transforms them into living documentation.

The OpenAPI generator will:

• 📃 Document domains, services and messages from your OpenAPI file (example)
• 📊 Visualise your architecture
• ⭐ Download your OpenAPI files
• 💅 Custom MDX components
• 🗄️ Auto versioning of your domains, services and messages
• ⭐ Discoverability feature (search, filter and more)
• ⭐ And much more...

Getting started​

To get started you can read the documentation or see the example project.

Summary​

EventCatalog is vendor and technology agnostic. This allow us to integrate with any system in the world and we already have a backlog of plugins (Backstage, OpenAPI, GitHub, AWS, Azure, Google, Solace, Gravitee and more...).

Today we launched our OpenAPI integration which allows you to automate your EventCatalog.

If you have any questions you can join us on our Discord server.

I'm happy to share the first integration plugin for EventCatalog has been released.

The EventCatalog AsyncAPI plugin connects your AsyncAPI files to EventCatalog and automates the hydration of your catalog, versioning and schema management.

What is AsyncAPI?​

The AsyncAPI specification is the industry standard for defining asynchronous APIs, with AsyncAPI you can define your servers, channels and messages. This gives architects and developers the ability to document their asynchronous APIs using an open standard.

From the website directly:

AsyncAPI is an open source initiative that seeks to improve the current state of Event-Driven Architectures (EDA). Our long-term goal is to make working with EDAs as easy as working with REST APIs. That goes from documentation to code generation, from discovery to event management, and beyond. (read more)

AsyncAPI is part of the Linux foundation has a fantastic tools defined and community behind the project.

Why integration with EventCatalog​

Over the past few years AsyncAPI has gained momentum and has become a great standard to help you document and govern your event-driven architectures. Many companies including LEGO, Zora Robotics, Walmart and Ebay are using AsyncAPI to help them build their event-driven architectures.

Our vision with EventCatalog is to help companies manage event-driven architecture discoverability and it's complexity through documentation and integration tools. Part of this vision is to automate some of this complexity and documentation for you. That's why we have integrated with AsyncAPI.

How the plugin works​

EventCatalog can be powered by generators. Generators can be used to automate the creation of your EventCatalog.

The AsyncAPI generator takes your AsyncAPI files and transform them into living documentation.

The AsyncAPI generator will:

• 📃 Document domains, services and messages from your AsyncAPI file (example)
• 📊 Visualise your architecture (demo)
• ⭐ Download your AsyncAPI files and message schemas form EventCatalog (e.g Avro, JSON) (demo)
• 💅 Custom MDX components (read more)
• 🗄️ Auto versioning of your domains, services and messages
• ⭐ Discoverability feature (search, filter and more) (demo)
• ⭐ And much more...

Getting started​

To get started you can read the documentation or see the example project.

You can also watch the video to learn more.

Summary​

EventCatalog is vendor and technology agnostic. This allow us to integrate with any system in the world and we already have a backlog of plugins (Backstage, OpenAPI, GitHub, AWS, Azure, Google, Solace, Gravitee and more...).

Today we launched our first integration with AsyncAPI which allows you to automate your EventCatalog.

If you have any questions you can join us on our Discord server.

It’s been a couple of months since I left my full time job at AWS to pursue my passion for event-driven architecture (EventCatalog) and cloud computing (Wing). I wanted to share an update on the exciting changes we rolled out for EventCatalog in August, it's been a busy month.

Introduced Flows​

Version 2.5.0 introduced Flows. Flows give you the ability to document business features, workflows and EDA choreography.

I’m super excited with this feature as it lets you connect your documented services and messages in a way that wasn't possible before. Hopefully flows can help you visualize and document your business workflows, that can be shared with new engineers, product owners and others that may be interested.

EventCatalog is not just a tool for technical teams, I believe it has the ability to bring the organisation together, following practices I believe can add huge value to your event-driven architecture including domain-driven design, event storming, event modelling.

If you would like to learn more about flows you can read the announcement, read the docs are even try it yourself on the demo.

Audit changes with changelogs​

When we build our event-driven architectures, things are changing all the time, this can be implementation details, business requirements or messages being added or removed.

Either way, things are changing and the context to change gets lost over time.

EventCatalog now supports changelogs which give you the ability to audit your changes, do diffs between messages, and give engineers context to why things have changed. A simple example could be documenting why a property on a schema was removed, or why a service no longer accepts a command.

Changelogs are powered by markdown files, and simple to get started. Once you define your changelog users can view your domain, service or message change log in it’s own dedicated page on your Catalog.

To get started you can read the documentation or read the announcement.

Introducing custom components​

EventCatalog now supports custom components. This gives you the ability to add custom UI components into your pages. This allows you to create dynamic templates, reuse markdown across pages, client side JavaScript and more.

Custom components allows you to:

• Share snippets across pages
• Style with Tailwind CSS
• Embed client side JavaScript into your catalog
• Dynamic templating

To get started you can read the announcement or checkout the docs to create your first component.

Semver support for resources in your Catalog​

EventCatalog lets you document your domains, services and messages. At the moment domains contain services and services contain messages.

To connect resources together you used to have to specify the exact version and the resource to the resource, but now versions are optional and also support semver syntax!

Exact versioning it still supported, but semver gives you more options.

//before
---
id: InventoryService
version: 0.0.2
receives:
  - id: OrderConfirmed
    version: 0.0.1
  - id: OrderCancelled
    version: 0.0.1
sends:
  - id: InventoryAdjusted
    version: 0.0.4
  - id: OutOfStock
    version: 0.0.3
---

//after
---
id: InventoryService
version: 0.0.2
receives:
	// No version given, latest is assumed
  - id: OrderConfirmed
  // Latest minor version
  - id: OrderCancelled
    version: 0.0.x
sends:
  // latest version
  - id: InventoryAdjusted
    version: latest
  // exact version  
  - id: OutOfStock
    version: 0.0.3
---

Other things to celebrate​

EventCatalog continues to gain traction and help the community which is great to see. Here are a few more things worth mentioning and celebrating!

Improvements to EventCatalog

• New UI improvements to the visualizer
• Embed flows into your pages with the new Flow component.
• Create custom landing pages
• Added new functions to the EventCatalog SDK

Project updates

• EventCatalog got it first project sponsor from Hookdeck ♥️
• EDA Visuals (my other project) has now reached 10,000 downloads!
  • Free content to learn about event-driven architectures
• EventCatalog discord now has 749 members 🙏
• 1000 catalogs were created in August
• New contributors added total of 41 contributors to EventCatalog

Need help?​

EventCatalog now offers professional services. These range from workshops, to getting hands on to help you and your teams build your EventCatalog, setup automation and host your catalog. If you are interested in talking you can reach out to me on LinkedIn or email at hello@eventcatalog.dev

Want to learn more about event-driven architectures?

I have created free resources for you to dive deeper into event-driven architectures called EDA Visuals. EDA visuals are designs I have made with extra resources. You can view them and download the book for free!

Want to understand why EventCatalog exists? I explain the problems with event-driven architecture and complexity and ways you can solve it with standards, practices and open source solutions.

Want to sponsor EventCatalog?​

EventCatalog is open source, if you want to help make the project sustainable we welcome sponsors to the project. As a sponsor of EventCatalog we will add your logo to our website, EDA visuals and more.

If you are interested please feel free to reach out!

Summary​

August has been a busy month, with the help of the EventCatalog community we were able to ship some great features, see growth in the project and start to stabilise the project.

I’m super passionate about event-driven architecture governance and solving complexity issues and I believe EventCatalog is on the way to help solve many of these issues.

We still have many more features to explore, and problems to solve and I can’t wait to see what’s possible.

If you have any questions, get stuck or want to join our community you can join us on our Discord server.

Until next time!, Dave

EventCatalog 2.5.0 is out now! This release includes the new resource flows, visualizer improvements, and various bug fixes.
This release includes the following highlights:

• ⭐️ Document business features and workflows with the new content type "Flows"
• ⭐️ Simplified visualizer and visual changes
• ⭐️ Fixing domains visualizer
• ⭐️ Astro updates

Introducing Flows​

EventCatalog 2.5.0 introduces the new resource type Flows.

Flows give you the ability to document business features, workflows and EDA choreography.

Interactions with your systems may happen across many services, external services, domains and messages. Flows gives you the ability to document these for your architects and developers.

Example of a flow​

An example of a flow could be when a user cancels a subscription in your system (see example).

When a user cancels a subscription many services and messages can be send between each other.

1. User clicks to cancel subscription (CancelSubscription command is sent)
2. Subscription Service accepts command, and processes cancellation (e.g external system Stripe)
3. Subscription service publishes Success/Failed events (SubscriptionCancelled, SubscriptionCancellationFailed event)
4. Notification service listens for events and sends emails (Email )
5. and so on...

These steps define what happens when a user would cancel a subscription in our business.

This single transaction for a user may cross across many services, publish and consume many messages and also interact with external systems.

EventCatalog allows you to document these flows linking to your existing services and messages.

---
# id of the flow
id: "CancelSubscriptionFlow"

# Display name of the flow, rendered in EventCatalog
name: "User Cancels Subscription"

# version for your flow 
version: "0.0.1"

# Short summary of your event
summary: "Flow for when a user has cancelled a subscription"

# A list of steps for your flow
steps:
  
  # id of your step, required for linking between stages in your flow
  - id: "cancel_subscription_initiated"
    # rendered title of your step
    title: "Cancels Subscription"
    # Short summary of a step
    summary: "User cancels their subscription"
    # Defining an actor will render an actor node in the graph.
    actor:
      name: "User"
    # What happens next? Define the next step  
    next_step: 
      id: "cancel_subscription_request"
      label: "Initiate subscription cancellation"

  - id: "cancel_subscription_request"
    title: "Cancel Subscription"
    # This step is a message, include the message and version
    message:
      id: "CancelSubscription"
      version: "0.0.1"
    next_step: 
      id: "subscription_service"
      label: "Proceed to subscription service"

  - id: "stripe_integration"
    title: "Stripe"
    # This is an external system (e.g Stripe)
    externalSystem:
      name: "Stripe"
      summary: "3rd party payment system"
      url: "https://stripe.com/"
    next_step: 
      id: "subscription_service"
      label: "Return to subscription service"

  - id: "subscription_service"
    title: "Subscription Service"
    # This node is a service, include that.
    service:
      id: "SubscriptionService"
      version: "0.0.1"
    # Define multiple steps
    next_steps:
      - id: "stripe_integration"
        label: "Cancel subscription via Stripe"
      - id: "subscription_cancelled"
        label: "Successful cancellation"
      - id: "subscription_rejected"
        label: "Failed cancellation"

  - id: "subscription_cancelled"
    title: "Subscription has been Cancelled"
    message:
      id: "UserSubscriptionCancelled"
      version: "0.0.1"
    next_step:
      id: "notification_service"
      label: "Email customer"

  - id: "subscription_rejected"
    title: "Subscription cancellation has been rejected"

  - id: "notification_service"
    title: "Notifications Service"
    service:
      id: "NotificationService"
      version: "0.0.2"

---

This flow documents what happens when a User Cancels Subscription in our system. 

<NodeGraph />

<!-- Add any markdown you want, the workflow will also render in its own page /docs/flows/{Flow}/{version} -->

Flows let you visualize your services, commands, events, external services and actors.

Read the getting started guide to get started or API documentation.

Embedding flows into your pages​

Flows can also be added to your domains, services and messages pages in EventCatalog with the new <Flow/> component.

Adding a flow component into your page will render the flow directly into your page. This can be a great way to document business workflows, features and event choreography and attach them to your domains and services.

See example of the Flow component on EventCatalog demo

Simplified visualizer and visual changes​

The EventCatalog visualizer allows architects and developers to visualize their event-driven architectures.

Previously the visualizer showed all versions in the navigation bar, making it hard for folks to find resources they need if many versions are shown.

The visualizer now shows the latest version of domain, service or message. Simplifying the navigation.

Visualizer edges have also been adjusted, making it easier to see the lines between nodes and arrows between domains, services and message

If you still need to see a previous version of the resource, you can change the version in the URL.

Astro updates​

EventCatalog is powered by Astro. EventCatalog has now been updated to 4.14.

Getting started​

Update your eventcatalog version to @eventcatalog/core: 2.5.1.

or create your new catalog using the command:

npx @eventcatalog/create-eventcatalog my-catalog

Are you looking for help with your event-driven architecture?

Do you need help with?

• EventStorming and Domain-driven design?
  • Transforming the output into your EventCatalog
  • Documenting your domains, bounded context, services, events, commands and flows.
• Managing event-driven architecture complexity
• EDA governance and standards
• Designing and implementing your EventCatalog
• Automating/Deploying your EventCatalog

Let's work together.

Hi, I’m Dave Boyne, and I specialize in helping companies worldwide understand and build event-driven architectures. I’m the author of EDA Visuals and the founder of EventCatalog. My contributions extend to open-source specifications for event-driven architectures (AsyncAPI), as well as creating tools, keynoting and speaking, and delivering workshops at conferences (e.g AWS:reInvent, GOTO Conference)

If you're interested in consultancy or workshops, don’t hesitate to reach out at hello@eventcatalog.dev.

I'm excited to share that EventCatalog 2.3.1 is now available, featuring support for custom components.

You can now add custom components to your domains, services and messages.

Custom components allows you to create dynamic templates, reuse markdown across pages, client-side JavaScript and more.

Example of a new custom component

1. Define your custom component in the new /components folder.

---
# Import data from your eventcatalog.config.js file
import config from "@config"
# Access passed-in component props, like `<MyComponent title="Hello, World" />`
const { subtitle } = Astro.props;
---

<main>
    <span>This catalog belongs to the company:{config.organizationName}</span>
    <span>Data given to this component {subtitle}</span>
</main>

2. Import and use your component in EventCatalog

---
id: OrderAccepted
name: Order Accepted
# ... other event data
---

<!-- Import the component into your page -->
import MyComponent from '@catalog/components/my-component.astro"

<!-- EventCatalog supports variables -->
export const subtitle = "This is my new subtitle"

# Overview 

This event represents when an order has been accepted on our system.

<!-- Render the component and pass props into it -->
<MyComponent subtitle="This is a component" />

<!-- Render the component and reference your resource -->
<MyComponent subtitle={frontmatter.name} />

<!-- Render the component with a local variable -->
<MyComponent subtitle={subtitle} />

Why custom components?​

EventCatalog provides a list of components out the box including Accordions, Schemas, OpenAPI and NodeGraphs.

Users of EventCatalog can now define their own components and use them across their catalog. This provides extra functionality and customization for your catalogs.

Component features include:

• Share snippets across pages
• Style with Tailwind CSS
• Embed client side JavaScript into your catalog
• Dynamic templating

Getting started​

If you already have an EventCatalog you need to upgrade to the version @eventcatalog/core@2.3.0.

Don't have a catalog?

You can try out the new features by installing a new catalog

npx @eventcatalog/create-eventcatalog@latest my-catalog

Summary​

EventCatalog now supports custom components.

Custom components give you the ability to build and share components across your domains, services and messages.

Custom components support styling with TailwindCSS, Client side JavaScript, Dynamic templating, data fetching and more.

If you have any questions, feature ideas, or would like to discuss EventCatalog features with your team, join our Discord community.

Using EventCatalog?​

Want to learn more about EventCatalog and how it can help you? Reach out to me on socials or Discord, and I would be happy to join a call with you and your team.

I'm excited to share that EventCatalog 2.2.0 is now available, featuring support for changelogs.

You can now add changelogs to your domains, services and messages (events/commands).

Why changelogs?​

In event-driven architectures, various components like domains, services, schemas, formats, and boundaries are constantly evolving. Unfortunately, the context or reason behind these changes often gets lost.

As a result, developers may begin to question architectural decisions, schema formats, service boundaries, and more. Without historical information, it can be challenging to share this knowledge, especially as team members leave or join the company.

EventCatalog changelogs are designed to address this issue.

Getting started​

EventCatalog gives you the ability to document your event-driven architecture through domains, services and messages.

These resource types can be versioned and now EventCatalog provides the ability to add changelogs by providing a changelog.md file along side your resource.

Example​

Changelog files are located along side your domain, service or message, this also includes any versioned resource.

---
createdAt: 2024-08-01
badges:
 - content: ⭐️ JSON Schema
   backgroundColor: purple
   textColor: purple
---

### Added support for JSON Schema

InventoryAdjusted uses Avro but now also supports JSON Draft 7.

```json title="Employee JSON Draft"
// labeled-line-markers.jsx
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "Employee",
"properties": {
 "Name": {
   "type": "string"
 },
 "Age": {
   "type": "integer"
 },
 "Town": {
   "type": "string"
 }
},
"required": ["Name", "Age", "Town"]
}

``

---
createdAt: 2024-08-01
---

### Service receives additional events

Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.

---
createdAt: 2024-08-01
---

### New service added to the Payment domain

Service now receives [OrderAmended](/docs/events/OrderAmended/0.0.1) and [UpdateInventory](/docs/commands/UpdateInventory/0.0.3) events.

Changelogs will be rendered into their own page. All changelog.md files for a given domain, service or message are gathered and listed in order of version number.

See example on the demo project.

Adding schema diffs, labels and more​

Changelogs are a great way to document diffs in your schemas. Add code blocks to your changelog and use the diff syntax in the codeblock.

Read more about code block features including diffs, labels, and frames for code blocks.

Summary​

EventCatalog now supports changelogs for domains, services and messages (events/commands).

You can use changelogs to audit and document changes within your architecture. Changelogs can be useful for teams and organizations that want to share historic information.

Changelogs are powered by changelog.md files you can add to any resource. EventCatalog will find your changelog files and render them in order of version.

Read the documentation to learn more and get started:

• Changelogs for domains
• Changelogs for services
• Changelogs for events and commands

If you have any questions, feature ideas, or would like to discuss EventCatalog features with your team, join our Discord community.

Want to learn more about EventCatalog and how it can help you? Reach out to me on socials or Discord, and I would be happy to join a call with you and your team.

I'm excited to announce the release of the new JavaScript/TypeScript EventCatalog SDK. This SDK is designed to help users programmatically interact with their EventCatalogs, streamlining the process of managing event-driven architectures.

EventCatalog aims to facilitate the discovery and documentation of event-driven architectures, regardless of the broker or technology used. The EventCatalog SDK is a step towards this vision.

Many EventCatalog users have requested integration support and automation capabilities (i.e GitHub Actions). With this SDK, we are starting to provide these options. Future releases will include broker integrations and plugins, expanding the SDK's functionality.

The new SDK enables CRUD operations on your domains, services, and messages within your Catalog. Additionally, it allows you to add files and schemas to these resources, enhancing your ability to manage and document your event-driven architecture efficiently.

Getting Started​

First, install the SDK by running:

pnpm add @eventcatalog/sdk

yarn add @eventcatalog/sdk

npm i @eventcatalog/sdk

Next, you need to initialize the SDK with the location of your catalog:

import utils from '@eventcatalog/sdk';

// tell utils where your EventCatalog path is
const { getEvent, writeEvent, versionEvent, rmEventById } = utils('/my-eventcatalog');

//  Write an event to EventCatalog (this would go to events/InventoryAdjusted)
await writeEvent({
  id: 'InventoryAdjusted',
  name: 'Inventory Adjusted',
  summary: 'Event raised when inventory has been adjusted',
  version: '1.0.0',
  markdown: `## Overview
  Inventory Adjusted is triggered when the inventory has been changed.
  <NodeGraph />
  `
})

// Get an event based on it's ID 
const event = await getEvent('InventoryAdjusted');

// Get an event based on its ID and version
const event = await getEvent('InventoryAdjusted', '0.0.1');

// Take the latest event and version it
await versionEvent('InventoryAdjusted');

// Remove the event from EventCatalog
await rmEventById('InventoryAdjusted');

You can find the complete documentation for the SDK on our documentation website.

What's next?​

We will continue to add new features to the SDK, with a major focus on open-source plugins and broker integrations.

A variety of open-source EventCatalog plugins will be developed, along with a CLI to create new plugins. EventCatalog will support configuration with both custom and off-the-shelf plugins, allowing integration with schema registries, AsyncAPI files, and more.

If you have any questions, feature ideas, or would like to discuss EventCatalog features with your team, join our Discord community.

Event-driven architectures share a common challenge: their complexity can quickly escalate as more domains, services, and messages are added.

As business requirements evolve and teams adapt, governing and understanding this distributed architecture becomes increasingly difficult. What begins as a straightforward system often transforms into a complex structure with minimal documentation and discoverability, leaving most people struggling to comprehend it (I share my thoughts on EDA complexity in this GOTO EDA Day 2024 keynote).

In January 2022 EventCatalog v1 was launched to help bring discoverability and documentation to event-driven architectures. Since its inception, EventCatalog has seen over 13,000 catalogs created, attracted 45 contributors, grown a community of more than 600 members on Discord and was added to Thoughtworks Technology Radar.

The growing popularity of EventCatalog in recent years highlights the challenges of complexity in building event-driven architectures. It also highlights the importance of discoverability and documentation. That's why I'm excited to announce the release of EventCatalog v2.

EventCatalog V2​

EventCatalog (v2) has been completely rewritten from the ground up, incorporating lessons from EventCatalog v1 and introducing a host of new features on a fresh foundation. These enhancements include:

• A refreshed UI and improved developer experience (demo)
• Documentation for new resources: domains, services, and messages (commands, events, and soon, queries)
• Visualizer support for all resources within EventCatalog
• A new discoverability feature that enables quick filtering and searching for resources in a tabular format (demo)
• Versioning capabilities for domains, services, and messages
• New landing pages for users and teams (demo)
• Rewritten using Astro for faster build times and reduce complexity
• Hot-reload support for catalog changes
• New components for your catalogs (read more)
• Ability to search your catalog (demo)
• Enterprise support
• And much more...

This new foundation enables faster development and future feature support, including schema registry, API support, broker integrations (plugins), and more.

If you already have a previous version of EventCatalog you can read the migration guide.

Getting started​

You can use the EventCatalog CLI tool you can create an EventCatalog in seconds.

# Install your new catalog
npx @eventcatalog/create-eventcatalog@latest [name]

# Example
npx @eventcatalog/create-eventcatalog@latest my-catalog

Read the installation guide for more information.

Already have an EventCatalog? Read the migration guide.

Introducing enterprise support​

EventCatalog now offers enterprise support, this support includes priority support, private support channels, custom integrations, priority feature development and more.

If you are using EventCatalog and would like to work together you can contact us on hello@eventcatalog.dev or read more details on the enterprise support page.

What’s next?​

EventCatalog v2 is just the start, next on the roadmap (July 2024) is plugin support and plugin documentation. EventCatalog's vision is to integrate with any broker in the world, which will be powered by custom plugins.

Other features include EventCatalog as a schema registry, API support, single sign on support, hosting options and much more.

If you have an idea for a feature or any questions feel free to raise an issue or join us on Discord.

Summary​

Complexity in event-driven architectures is inevitable, but we believe it can be managed through effective governance and documentation.

EventCatalog was initially created to assist teams in documenting their event-driven architectures and has proven valuable to hundreds of companies worldwide.

The new version of EventCatalog builds on this vision and mission, offering enhanced tools for managing the complexity of event-driven architectures through improved documentation and discoverability.

We are excited to see the possibilities and path that lie ahead.