topic-definition

KO | EN

gitlite — search

#python #mcp #claude-code #codex #llm #claude #ai #self-hosted #ai-agent #ai-agents #typescript #markdown

topic-definition

★ 63 Open GitHub ↗

AsyncAPI topic structure definition

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AsyncAPI Topic Definition

## Introduction

The purpose of this document is to describe how an AsyncAPI topic should be structured. The goal is to create a definition that suites most use cases and establish the foundation for community tooling and better interoperability between products when using AsyncAPI.

## What is a topic?

A topic is a string representing where an AsyncAPI can publish or subscribe. For the sake of comparison they are like URLs in a REST API.

## Components

Below we describe the components of an AsyncAPI topic.

### Organization

The name of the organization or company.

###### Example:

**`hitch`**.`accounts`.`1`.`event`.`user`.`signedup`

### Service/Team/Department

The service, team or department in charge of managing the message.

###### Example:

`hitch`.**`accounts`**.`1`.`event`.`user`.`signedup`

### Message version

The version of the message for the given service. This version number should remain the same unless changes in the messages are NOT backward compatible.

###### Example:

`hitch`.`accounts`.**`1`**.`event`.`user`.`signedup`

> Note: This version number is NOT related to your service or program version.

### Message type

It contains the type of the message, e.g., *is it a `command` or an `event`?*. This value should always be `event` unless you're trying to explicitly execute a command in another service, i.e., when using RPC.

###### Example:

`hitch`.`accounts`.`1`.**`event`**.`user`.`signedup`

`hitch`.`email`.`1`.**`command`**.`user`.`welcome`.`send`

### Resources and sub-resources

A word (or words) describing the resource the message refers to. For instance, if you're sending a message to notify a user has just signed up, the resource should be `user`. But, if you want to send a message to notify a user has just changed her full name, you could name it as `user.full_name`.

###### Example:

`hitch`.`accounts`.`1`.`event`.**`user`**.`signedup`

`hitch`.`email`.`1`.`command`.**`user`.`welcome`**.`send`

### Event/Command name

In case message type is `event`, this should be a verb **in past tense** describing what happened to the resource.

In case message type is `command`, this should be a verb **in infinitive form** describing what operation you want to perform.

###### Example:

`hitch`.`accounts`.`1`.`event`.`user`.**`signedup`**

`hitch`.`email`.`1`.`command`.`user`.`welcome`.**`send`**

### Status (optional)

A word describing the status of a previous **command**. When used, **the type of the topic MUST be `event`.** Allowed values are:

- `queued`: The command has been queued.
- `succeeded`: The command has been handled/executed successfully.
- `failed`: The command has failed.
- `done`: The command has finished.

###### Examples:

1. A user has just signed up:
`hitch`.`accounts`.`1`.`event`.`user`.`signedup`

2. We send a welcome email:
`hitch`.`email`.`1`.`command`.`user`.`welcome`.`send`

3. But the email gets queued, so the email service sends a message to:
`hitch`.`email`.`1`.`event`.`user`.`welcome`.`send`.`queued`

4. The email gets finally delivered and the email service sends messages to:
   - `hitch`.`email`.`1`.`event`.`user`.`welcome`.`send`.`succeeded`
   - `hitch`.`email`.`1`.`event`.`user`.`welcome`.`send`.`done`
5. Or, the recipient doesn't exist, and the email service sends messages to:
   - `hitch`.`email`.`1`.`event`.`user`.`welcome`.`send`.`failed`
   - `hitch`.`email`.`1`.`event`.`user`.`welcome`.`send`.`done`
6. The user sign up process has been completed so the accounts service sends:
`hitch`.`accounts`.`1`.`event`.`user`.`signup`.`done`

topic-definition

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README