Parameters in channel address

In the context of channel addresses within AsyncAPI documents, parameters play a crucial role in defining the dynamic components of an address. That aspect is particularly beneficial in setups like IoT, where topics are often assigned per device or device segment. In this scenario, your AsyncAPI document would describe a system composed of multiple channels. While these channels share the same definition, messages, and purpose, they differ in their channel addresses, which vary according to each device's identifier. To efficiently manage this setup, you provide a singular channel definition. The dynamic segment of each channel address, which corresponds to the device identifier, is then articulated through the use of parameters.

Add parameters

You can add parameters to the channel.address by adding a parameter between curly braces like {braces}. Next, use channel.parameters to define your parameters. Finally, leverage the components.parameters to enable reusable parameters' definitions across multiple channels.

The diagram below describes how to use reusable parameters in AsyncAPI.

First, configure the variables in address. Next, define reusable variables in components.parameters. Finally, ensure that your channel.parameters references definitions in the components.parameters using $ref.

Channels section

Here is an example of a parametrized channel address:

1  lightingMeasured:
2    address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
3    description: The topic on which measured values may be produced and consumed.
4    parameters:
5      streetlightId:
6        description: The ID of the streetlight.

In the above example, you can see a definition of a lightingMeasured channel that contains a streetlight parameter. During runtime, there can be two or more channels serving the same purpose, but with different devices. For example, you could have channels for smartylighting/streetlights/1/0/event/2/lighting/measured and smartylighting/streetlights/1/0/event/1/lighting/measured.

parameters section

In your AsyncAPI document, it's important to carefully define the components.parameters section. For each parameter utilized in the channel address, provide a comprehensive description along with other pertinent details. Avoid repeating the parameter definitions. For example:

1components:
2  parameters:
3    streetlightId:
4      description: The ID of the streetlight.

You can reuse parameters using the Reference Object like in the following example:

1    parameters:
2      streetlightId:
3        $ref: '#/components/parameters/streetlightId'

Here's the complete AsyncAPI document with the channels' parameters for the address field:

1asyncapi: 3.0.0
2info:
3  title: Example API
4  version: '1.0.0'
5channels:
6  lightingMeasured:
7    address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
8    description: The topic on which measured values may be produced and consumed.
9    parameters:
10      streetlightId:
11        $ref: '#/components/parameters/streetlightId'
12components:
13  parameters:
14    streetlightId:
15      description: The ID of the streetlight.