Hello world

Let's define an application that's capable of receiving a "hello {name}" message:

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5channels:
6  hello:
7    address: 'hello'
8    messages:
9      sayHelloMessage:
10        payload:
11          type: string
12          pattern: '^hello .+$'
13operations:
14  receiveHello:
15    action: 'receive'
16    channel:
17      $ref: '#/channels/hello'

Let's get into the details of this sample AsyncAPI document:

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5channels:
6  hello:
7    address: 'hello'
8    messages:
9      sayHelloMessage:
10        payload:
11          type: string
12          pattern: '^hello .+$'
13operations:
14  receiveHello:
15    action: 'receive'
16    channel:
17      $ref: '#/channels/hello'

The first line of the specification starts with the document type asyncapi and the version (3.0.0). That line doesn't have to be the first one, but it's a best practice.

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5channels:
6  hello:
7    address: 'hello'
8    messages:
9      sayHelloMessage:
10        payload:
11          type: string
12          pattern: '^hello .+$'
13operations:
14  receiveHello:
15    action: 'receive'
16    channel:
17      $ref: '#/channels/hello'

The info object contains the minimum required information about the application. It contains the title, which is a memorable name for the API, and the version. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API.

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5channels:
6  hello:
7    address: 'hello'
8    messages:
9      sayHelloMessage:
10        payload:
11          type: string
12          pattern: '^hello .+$'
13operations:
14  receiveHello:
15    action: 'receive'
16    channel:
17      $ref: '#/channels/hello'

The channels section of the specification houses all of the mediums where messages flow through. For example, some systems use topic, event name or routing key. Different kinds of information flow through each channel similar to the analogy of TV channels.

You only have one channel called hello, and you see what message is available in this channel and how it must be structured. The payload object defines that the message must be a string and match the given regular expression in a string format such as hello {name}.

1asyncapi: 3.0.0
2info:
3  title: Hello world application
4  version: '0.1.0'
5channels:
6  hello:
7    address: 'hello'
8    messages:
9      sayHelloMessage:
10        payload:
11          type: string
12          pattern: '^hello .+$'
13operations:
14  receiveHello:
15    action: 'receive'
16    channel:
17      $ref: '#/channels/hello'

The operations section is where you describe what the application is doing. Each operation has a unique identifier for example, receiveHello.

In the above example, you see that the Hello world application is a consumer listening to the sayHelloMessage message from the hello channel. In other words, you can say that the Hello world application subscribes to the hello topic to receive the sayHelloMessage message. That AsyncAPI document describes what the Hello world application is doing, not what others can do with it.