asyncapi-step-by-step.md

1. Choose your editor

• AsyncAPI Studio
• AsyncAPI CLI
• VSCode extension
• IDEA plugin

2. Choose between YAML or JSON

Yes, just joking, no human would choose JSON...right?

3. Specify AsyncAPI version

We release regularly every few months. Learn more from official release process instruction.

asyncapi: 2.4.0 #https://github.com/asyncapi/spec/releases

4. Provide overal info about the App

info:
  title: Shrek App
  version: '1.0.0'
  description: | # Markdown supported, multiline YAML to the rescue
    Purpose of this app is to have some fun with AsyncAPI and WebSocket and define an interface for ... Shrek.
    ![](https://media.giphy.com/media/10Ug6rDDuG3YoU/giphy-downsized.gif)
    You can use this API to chat with Shrek bot or to get updates about artifical travels to different locations.

5. Specify how users can connect to the App

In case you do not like WebSocket example. Take this Kafka example

servers:
  swamp:
    url: localhost
    protocol: ws

Sometimes it is the server that points directly to the app (WebSocket) but can also be a remote server, broker address.

6. What are the communication channels

In case of WebSockets you could say these are like endpoints. In case of most broker-centric architecture they are also called topics.

channels:
  /chat: {}
  /travel/status: {}

7. What are the messages there floating in your system

Components enable you to better structure information in AsyncAPI files. It is all about the readability after all.

components:
  messages: # events
    chatMessage:
      summary: Message that you send or receive from chat
      payload:
        type: string

8. Maybe let's first try with schema now

components:
  schemas: # payload
    travelData:
        type: object
        properties:
            destination:
                description: Name of travel destination.
                type: string
            distance:
                description: How much distance left to the target.
                type: string
            arrival:
                description: Time left to get there.
                type: string

and now reference inside the message.

components:
  messages:
    travelInfo:
      summary: Message that contains information about travel status.
      payload: 
        $ref: "#/components/schemas/travelData"
      examples:
        - payload:
            destination: Far far away
            distance: Beyond the seven mountains and seven forests
            arrival: Pretty soon

9. Reference messages in channels

Remember that you also need to specify if message is something users can consume or actually send to the app.

channels:
  /chat:
    subscribe:
      summary: Client can receive chat messages.
      operationId: subChatMessage
      message:
        $ref: '#/components/messages/chatMessage'
    publish:
      summary: Client can send chat messages.
      operationId: pubChatMessage
      message:
        $ref: '#/components/messages/chatMessage'
  /travel/status:
    subscribe:
      summary: Client can receive travel info status.
      operationId: subTravelInfo
      message:
        $ref: '#/components/messages/travelInfo'

10. Use bindings to specify query params for the channel

channels:
  /travel/status:
    subscribe:
      summary: Client can receive travel info status.
      operationId: subTravelInfo
      message:
        $ref: '#/components/messages/travelInfo'
    bindings: 
      ws:
        bindingVersion: 0.1.0
        query:
          type: object
          description: |
            You can specify to receive travel status info from specific location
          properties:
            destination:
              type: string
              description: Airport code
              enum:
                - BCN
                - KTW
                - LCY

11. Provide info about response using extension

Let's say your chat has an option to specify when the answer to the chat message should go.

Like you have email from some system that specifies you should not reply, but do something else.

components:
  messages: # events
    chatMessage:
      summary: Message that you send or receive from chat
      payload:
        type: string
      x-response:
        description: Location of the information about where reply should be sent to
        location: "$message.payload#/replyTo"

BONUS

• You could have just copy this AsyncAPI file instead of following step by step
• For traits example just have a look at this Kafka example
• For more reuse examples with $ref across files, look at this social media example