Create AsyncAPI document

Introduction

In this tutorial, you'll learn how to create an AsyncAPI document based on a sample real-world use case. Additionally, you will learn about event-driven architecture, message brokers, pub/sub pattern.

Let's pretend you have a company called Smarty Lighting, and you install smart-city streetlight lighting systems. Such a smart lighting system is an Internet of Things (IoT) use case. You will create a Smarty Lighting Streetlights application using Node.js and Mosquitto (MQTT) as the message broker. Your application will allow you to manage city lights remotely.

You want to build a system that can turn streetlights on and off based on their environmental conditions:

• You will implement an event-driven architecture (EDA) with a message broker in its "center."

• The Streetlights application will receive information about environmental lighting conditions.

• The Streetlights application will connect to the broker and receive a stream of events from all the streetlights devices reporting their conditions.

• The Streetlights application is unaware of how many streetlights devices send measurement events to the broker; it just connects to the broker and receives all events.

Background context

Event-driven architecture (EDA) is a design pattern built around the production, detection, and reaction to events that take place in time. In this pattern, a message broker, event publishers, and subscribers are its main components for event exchange within microservices.

Message brokers enables asynchronous communications between services so that the sending service need not wait for the receiving service’s reply. That allows interdependent services to “talk” with one another directly, even if they were written in different languages or implemented on different platforms.

Furthermore, the Pub/sub is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission.

MQTT, is a well-known protocol that is widely used in IoT applications because it was created particularly to address machine-to-machine (M2M) communication.

Create AsyncAPI document

In this step, you will create an AsyncAPI document to describe the Streelights application. It will help you generate the code and the documentation later on.

To create one, you can either use the AsyncAPI Studio or the AsyncAPI CLI, depending on your project's needs.

Create the following specification document titled asyncapi with a .yaml extension.

1asyncapi: 3.0.0
2info:
3  title: Streetlights App
4  version: '1.0.0'
5  description: |
6    The Smartylighting Streetlights application allows you
7    to remotely manage the city lights.
8  license:
9    name: Apache 2.0
10    url: 'https://www.apache.org/licenses/LICENSE-2.0'
11servers:
12  mosquitto:
13    host: test.mosquitto.org
14    protocol: mqtt
15channels:
16  lightMeasured:
17    address: 'light/measured'
18    messages:
19      lightMeasuredMessage:
20        name: LightMeasured
21        payload:
22          type: object
23          properties:
24            id:
25              type: integer
26              minimum: 0
27              description: ID of the streetlight.
28            lumens:
29              type: integer
30              minimum: 0
31              description: Light intensity measured in lumens.
32            sentAt:
33              type: string
34              format: date-time
35              description: Date and time when the message was sent.
36operations:
37  onLightMeasured:
38    action: 'receive'
39    summary: Information about environmental lighting conditions for a particular streetlight.
40    channel:
41      $ref: '#/channels/lightMeasured'

Let's break the above code snippet down into pieces:

1asyncapi: 3.0.0
2info:
3  title: Streetlights App
4  version: '1.0.0'
5  description: |
6    The Smartylighting Streetlights application allows you
7    to remotely manage the city lights.
8  license:
9    name: Apache 2.0
10    url: 'https://www.apache.org/licenses/LICENSE-2.0'

• The asyncapi field indicates you use the AsyncAPI version 3.0.0.

• The info field holds information about the Streetlights application. Here, the title, version, description, and license were defined.

Moving on, let's talk about the servers section:

1servers:
2  mosquitto:
3    host: test.mosquitto.org
4    protocol: mqtt

In this section, you point to the Eclipse Mosquitto message broker. The url points to a real broker instance hosted by the Mosquitto community, and the protocol is MQTT. If you do not want to use the test instance, you can spin up your own broker locally with docker run -it -p 1883:1883 eclipse-mosquitto:1.5. Remember to change the url to mqtt://localhost.

Now, let's move on to the channels section. In the servers section, you specified how to connect to the broker where the application sends messages to or receives messages from. In channels, you go into more details about the connection address inside the broker. (Example: A topic name that specifies what messages are available in the channel.)

1channels:
2  lightMeasured:
3    address: 'light/measured'
4    messages:
5      lightMeasuredMessage:
6        name: LightMeasured
7        payload:
8          redacted for brevity

In this example, light/measured is the channel address. From the Streetlight application example perspective, it means that light/measured is the topic's name in the MQTT broker.

Next is the payload property. It is used to understand how the event should look like when publishing to that channel

1      payload:
2        type: object
3        properties:
4          id:
5            type: integer
6            minimum: 0
7            description: Id of the streetlight.
8          lumens:
9            type: integer
10            minimum: 0
11            description: Light intensity measured in lumens.
12          sentAt:
13            type: string
14            format: date-time
15            description: Date and time when the message was sent.

The payload property defines the event's content using AsyncAPI schemas. It means that your event payload should contain an id and a lumens property —which are integers bigger than zero—and a sentAt property which should be a string containing a date and time.

JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, such as Avro.

The last section is operations, where you describe what the application described in the AsyncAPI document is doing.

1operations:
2  onLightMeasured:
3    action: 'receive'
4    summary: Information about environmental lighting conditions for a particular streetlight.
5    channel:
6      $ref: '#/channels/lightMeasured'

You can see that the Streetlight application is a consumer that only receives events from the broker. Using the mandatory channel field, you specify with $ref what channel the events come from.

The onLightMeasured key property describes the function or method name that takes care of this functionality in the generated code. It is a unique ID of the operation across the whole document.

Summary

In this tutorial, you learned how to create an AsyncAPI specification document via a real-life example with an IoT use case.

Your finished document is just a starting point; you must add your business logic. Take some time to play with it. There are still lots of things to be covered, but the intent of this tutorial is to make it simple for you to get an idea of the potential.

Next steps

Now that you've completed this tutorial, you can proceed to learn how to validate your AsyncAPI document with AsyncAPI Studio.