Hello world

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

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

Let's get into the details of this sample specification:

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

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

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^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.

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^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.

In this example, you only have one channel called hello. The sample application subscribes to this channel to receive hello {name} messages.

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

You can read the highlighted lines as:

This is the payload of the message that the Hello world application is subscribed to. You can publish the message to the hello channel and the Hello world application will receive it.

1
2
3
4
5
6
7
8
9
10
11
asyncapi: 2.5.0
info:
  title: Hello world application
  version: '0.1.0'
channels:
  hello:
    publish:
      message:
        payload:
          type: string
          pattern: '^hello .+$'

The payload object defines how the message must be structured. In this example, the message must be a string and match the given regular expression in the format hello {name} string.