From 7fccf5066a3292dba4dbf2829cfc9e0ef1882729 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 17 Jul 2023 14:37:41 +0600 Subject: [PATCH 1/8] added adding channel page --- .../concepts/asyncapi-document/_section.md | 4 + .../asyncapi-document/adding_channels.md | 93 +++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/adding_channels.md diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md new file mode 100644 index 00000000000..dc0a53d07ea --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -0,0 +1,4 @@ +--- +title: 'AsyncAPI Document' +weight: 0 +--- \ No newline at end of file diff --git a/pages/docs/concepts/asyncapi-document/adding_channels.md b/pages/docs/concepts/asyncapi-document/adding_channels.md new file mode 100644 index 00000000000..6cc18cbabda --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding_channels.md @@ -0,0 +1,93 @@ +--- +title: Adding Channels +weight: 200 +--- + +Adding [channels](../channel.md) in AsyncAPI specification, allows to organize and categorize messages, route messages to the appropriate consumers, decouple producers and consumers, scale and extend the API, and provide clear documentation and communication about API's communication patterns. + +In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. It is important to refer to the specific terminology used in the corresponding documentation or specifications of the messaging system or protocol being utilized. + +Here's an example of how to define channels: +To add a channel in an AsyncAPI document, you need to define it in the channels object in the root of your AsyncAPI document. For example, consider the following AsyncAPI definition snippet + +```yml +channels: + user/signedup: + subscribe: + message: + $ref: '#/components/messages/UserSignedUp' +``` + +In this example, `user/signedup` is the channel. This means that the application allows consumers to subscribe to the `user/signedup` channel to receive userSignUp messages. + +## Channel Server Relationship + +Channels and servers have a close relationship in asynchronous messaging systems. Channels act as communication pathways for messages, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on their purpose or topic. Servers, acting as producers, generate messages and publish them to specific channels. Consumers, including servers, subscribe to channels to receive the messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. + +Here's an example on how channels and servers can be intertwined: + +```yml +asyncapi: 3.0.0 +info: + title: User Signup API + version: '1.0.0' +channels: + user/signedup: + subscribe: + summary: Subscribes to user signup events + message: + $ref: '#/components/messages/UserSignedUp' + +``` + +The example demonstrates a channel named `user/signedup` where clients can subscribe to receive user signup events, establishing a communication pathway between the server and the clients for notifying them about user signup events. + +## Channel Availability on Specific Servers + +In a distributed messaging system, a channel can be designed to be available on all servers. This means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. + +Here is an example of how you might specify that a channel is available only on certain servers: + +```yml +channels: + user/signedup: + subscribe: + summary: Subscribes to user signup events + message: + $ref: '#/components/messages/UserSignedUp' + +servers: + serverA: + url: serverA.example.com + serverB: + url: serverB.example.com +``` + +In this code code defines a channel `user/signedup` for subscribing to user signup events, and two servers `Server A` and `Server B` with their respective URLs, enabling clients to receive user signup notifications from either server. + +So, when one specify a channel and servers, it allows the AsyncAPI document to clarify where each channel can be found. This is particularly beneficial in complex systems where different servers might be responsible for different sets of operations. + +## Multiple Channels in Single Server + +Having multiple channels in one server allows for better organization and management of different types of events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to subscribe to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. + +```yml +channels: + user/signedup: + subscribe: + summary: Subscribes to user signup events + message: + $ref: '#/components/messages/UserSignedUp' + user/activated: + subscribe: + summary: Subscribes to user activation events + message: + $ref: '#/components/messages/UserActivated' + +servers: + serverA: + url: serverA.example.com + +``` + +The YAML code defines multiple channels, `user/signedup` and `user/activated`, within the `serverA` server, enabling clients to subscribe and receive events for user signup and activation. From 389f2c695961c9ad1ac122243e5b401d3cadcd5c Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 17 Jul 2023 14:57:50 +0600 Subject: [PATCH 2/8] adding mermaid diagram --- .../asyncapi-document/adding_channels.md | 91 ++++++++++++++++++- 1 file changed, 89 insertions(+), 2 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding_channels.md b/pages/docs/concepts/asyncapi-document/adding_channels.md index 6cc18cbabda..676227184ae 100644 --- a/pages/docs/concepts/asyncapi-document/adding_channels.md +++ b/pages/docs/concepts/asyncapi-document/adding_channels.md @@ -5,10 +5,9 @@ weight: 200 Adding [channels](../channel.md) in AsyncAPI specification, allows to organize and categorize messages, route messages to the appropriate consumers, decouple producers and consumers, scale and extend the API, and provide clear documentation and communication about API's communication patterns. -In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. It is important to refer to the specific terminology used in the corresponding documentation or specifications of the messaging system or protocol being utilized. +In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. Here's an example of how to define channels: -To add a channel in an AsyncAPI document, you need to define it in the channels object in the root of your AsyncAPI document. For example, consider the following AsyncAPI definition snippet ```yml channels: @@ -20,10 +19,52 @@ channels: In this example, `user/signedup` is the channel. This means that the application allows consumers to subscribe to the `user/signedup` channel to receive userSignUp messages. +```mermaid +graph LR + subgraph Producer + p1(Producers) + end + + subgraph Channels + c1{user/signedup} + end + + subgraph Consumer + s1(Subscribers) + end + + subgraph Messages + m1($ref: '#/components/messages/UserSignedUp') + end + + p1 --> c1 + c1 --> s1 + s1 --> m1 +``` + +The diagram above represents the flow of communication between producers, channels, consumers, and messages. Producers generate messages, which are transmitted through the `user/signedup` channel and received by subscribing consumers. The actual data being transmitted is specified as `$ref: '#/components/messages/UserSignedUp'`. + ## Channel Server Relationship Channels and servers have a close relationship in asynchronous messaging systems. Channels act as communication pathways for messages, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on their purpose or topic. Servers, acting as producers, generate messages and publish them to specific channels. Consumers, including servers, subscribe to channels to receive the messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. +```mermaid +graph TD + subgraph Servers + s1(Servers) + s2(Servers) + end + + subgraph Channels + c1{Channels} + end + + s1 --> c1 + s2 --> c1 + c1 --> s1 + c1 --> s2 +``` + Here's an example on how channels and servers can be intertwined: ```yml @@ -46,6 +87,33 @@ The example demonstrates a channel named `user/signedup` where clients can subsc In a distributed messaging system, a channel can be designed to be available on all servers. This means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. +```mermaid +graph TD + subgraph Clients + c1(Client 1) + c2(Client 2) + c3(Client 3) + end + + subgraph Servers + s1(Server 1) + s2(Server 2) + s3(Server 3) + end + + subgraph Channel + ch(Channel) + end + + c1 --- ch + c2 --- ch + c3 --- ch + + s1 --- ch + s2 --- ch + s3 --- ch +``` + Here is an example of how you might specify that a channel is available only on certain servers: ```yml @@ -71,6 +139,25 @@ So, when one specify a channel and servers, it allows the AsyncAPI document to c Having multiple channels in one server allows for better organization and management of different types of events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to subscribe to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. +```mermaid +graph TD + subgraph Server + s1(Server) + end + + subgraph Channels + c1{Channel 1} + c2{Channel 2} + c3{Channel 3} + end + + s1 --> c1 + s1 --> c2 + s1 --> c3 +``` + +Here is an example of multiple channels are available on certain servers: + ```yml channels: user/signedup: From 046edfc056477cfff5b601158d5055e99775936e Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 18 Jul 2023 20:55:44 +0600 Subject: [PATCH 3/8] update typo --- pages/docs/concepts/asyncapi-document/adding_channels.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding_channels.md b/pages/docs/concepts/asyncapi-document/adding_channels.md index 676227184ae..422b35df45d 100644 --- a/pages/docs/concepts/asyncapi-document/adding_channels.md +++ b/pages/docs/concepts/asyncapi-document/adding_channels.md @@ -7,7 +7,7 @@ Adding [channels](../channel.md) in AsyncAPI specification, allows to organize a In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. -Here's an example of how to define channels: +Here's an example of how to define channels - ```yml channels: @@ -65,7 +65,7 @@ graph TD c1 --> s2 ``` -Here's an example on how channels and servers can be intertwined: +Here's an example on how channels and servers can be intertwined - ```yml asyncapi: 3.0.0 @@ -114,7 +114,7 @@ graph TD s3 --- ch ``` -Here is an example of how you might specify that a channel is available only on certain servers: +Here is an example of how you might specify that a channel is available only on certain servers - ```yml channels: @@ -156,7 +156,7 @@ graph TD s1 --> c3 ``` -Here is an example of multiple channels are available on certain servers: +Here is an example of multiple channels are available on certain servers - ```yml channels: From c07bab3c53b7d708ddc7324ee655bc7bc5833eb4 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 18 Jul 2023 21:11:58 +0600 Subject: [PATCH 4/8] update typo --- pages/docs/concepts/asyncapi-document/adding_channels.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding_channels.md b/pages/docs/concepts/asyncapi-document/adding_channels.md index 422b35df45d..676227184ae 100644 --- a/pages/docs/concepts/asyncapi-document/adding_channels.md +++ b/pages/docs/concepts/asyncapi-document/adding_channels.md @@ -7,7 +7,7 @@ Adding [channels](../channel.md) in AsyncAPI specification, allows to organize a In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. -Here's an example of how to define channels - +Here's an example of how to define channels: ```yml channels: @@ -65,7 +65,7 @@ graph TD c1 --> s2 ``` -Here's an example on how channels and servers can be intertwined - +Here's an example on how channels and servers can be intertwined: ```yml asyncapi: 3.0.0 @@ -114,7 +114,7 @@ graph TD s3 --- ch ``` -Here is an example of how you might specify that a channel is available only on certain servers - +Here is an example of how you might specify that a channel is available only on certain servers: ```yml channels: @@ -156,7 +156,7 @@ graph TD s1 --> c3 ``` -Here is an example of multiple channels are available on certain servers - +Here is an example of multiple channels are available on certain servers: ```yml channels: From 8855506a430d35627cc934db4749810274305c0e Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 24 Jul 2023 16:05:01 +0600 Subject: [PATCH 5/8] updating as per review --- .../asyncapi-document/adding-channels.md | 170 +++++++++++++++++ .../asyncapi-document/adding_channels.md | 180 ------------------ 2 files changed, 170 insertions(+), 180 deletions(-) create mode 100644 pages/docs/concepts/asyncapi-document/adding-channels.md delete mode 100644 pages/docs/concepts/asyncapi-document/adding_channels.md diff --git a/pages/docs/concepts/asyncapi-document/adding-channels.md b/pages/docs/concepts/asyncapi-document/adding-channels.md new file mode 100644 index 00000000000..348b2324594 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding-channels.md @@ -0,0 +1,170 @@ +--- +title: Adding Channels +weight: 200 +--- + +Adding [channels](../channel.md) in AsyncAPI specification allows organizing and categorizing messages, routing messages to the appropriate consumers, decoupling producers and consumers, scaling and extending the API, and providing clear documentation and communication about API's communication patterns. Additionally, alternative names for channels can be user-defined to suit specific context and preferences. + +```mermaid +graph TD + A[AsyncAPI Specification] + B[Channels] + C[Organizing and Categorizing Messages] + D[Routing Messages to Consumers] + E[Decoupling Producers and Consumers] + F[Scaling and Extending the API] + G[Providing Clear Documentation and Communication] + + style B fill:#47BCEE,stroke:#47BCEE; + + A --> B + B --> C + B --> D + B --> E + B --> F + B --> G + +``` + +The diagram above represents the flow of communication between producers, channels, consumers, and messages. + +Here is an example of how to define channels: + +```yml +asyncapi: 3.0.0 +info: + title: Channel Example + version: 0.1.0 +channels: + userSignedUp: + address: user/signedup + messages: + userSignedUp: + description: An event describing that a user just signed up. +``` + +This AsyncAPI specification sets up an interface for a `userSignedUp` channel, where the `address` field holds the actual address of the channel (`user/signedup`). + +## Channel Server Relationship + +Channels and [servers](../server.md) have a close relationship in asynchronous messaging systems. Channels act as message communication pathways, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on purpose or topic. Acting as producers, Servers generate messages and publish them to specific channels. Consumers, including servers, send to channels to receive messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. + +```mermaid +graph TD + subgraph Servers + s1(Servers) + s2(Servers) + end + + subgraph Channels + c1{Channels} + end + + style c1 fill:#47BCEE,stroke:#47BCEE; + + s1 --> c1 + s2 --> c1 + c1 --> s1 + c1 --> s2 +``` + +### Channel Availability on Specific Servers + +A channel can be designed to be available on all servers, which means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. + +```mermaid +graph TD + subgraph Clients + c1(Client 1) + c2(Client 2) + c3(Client 3) + end + + subgraph Servers + s1(Server 1) + s2(Server 2) + s3(Server 3) + end + + subgraph Channel + ch(Channel) + end + + style ch fill:#47BCEE,stroke:#47BCEE; + + c1 --- ch + c2 --- ch + c3 --- ch + + s1 --- ch + s2 --- ch + s3 --- ch +``` + +Here is an example of how you might specify that a channel is available only on specific servers: + +```yml +channels: + userSignedUp: + address: user/signedup + messages: + userSignedUp: + description: An event describing that a user just signed up. +servers: + serverA: + url: serverA.example.com + serverB: + url: serverB.example.com +``` + +The above code defines a channel `user/signedup` for subscribing to user signup events and two servers, `Server A` and `Server B`, with their respective URLs, enabling clients to receive user signup notifications from either server. + +Specifying a channel and servers allows the AsyncAPI document to clarify where each channel can be found. This method is particularly beneficial in complex systems where different servers might be responsible for different operations. + +### Multiple Channels in Single Server + +Having multiple channels in one server allows for better organization and management of different events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to send to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. + +```mermaid +graph TD + subgraph Server + s1(Server) + end + + subgraph Channels + c1{Channel 1} + c2{Channel 2} + c3{Channel 3} + end + + style c1 fill:#47BCEE,stroke:#47BCEE; + style c2 fill:#47BCEE,stroke:#47BCEE; + style c3 fill:#47BCEE,stroke:#47BCEE; + + s1 --> c1 + s1 --> c2 + s1 --> c3 +``` + +Here is an example of multiple channels available on specific servers: + +```yml +channels: + userSignedUp: + address: user/signedup + messages: + userSignedUp: + description: An event describing that a user just signed up. + userActivated: + address: user/activated + messages: + userActivated: + description: An event describing that user activation events. +servers: + serverA: + url: serverA.example.com +``` + +The YAML code defines multiple channels, `user/signedup` and `user/activated`, within the `serverA` server, enabling clients to subscribe and receive user signup and activation events. + +To know more details on how to add server check [add servers](add-server.md). diff --git a/pages/docs/concepts/asyncapi-document/adding_channels.md b/pages/docs/concepts/asyncapi-document/adding_channels.md deleted file mode 100644 index 676227184ae..00000000000 --- a/pages/docs/concepts/asyncapi-document/adding_channels.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Adding Channels -weight: 200 ---- - -Adding [channels](../channel.md) in AsyncAPI specification, allows to organize and categorize messages, route messages to the appropriate consumers, decouple producers and consumers, scale and extend the API, and provide clear documentation and communication about API's communication patterns. - -In addition to the term "channel," alternative names can be used to refer to the concept of channels in asynchronous messaging systems. These names may vary depending on the messaging protocol or system being used. Some examples include "topic," "queue," "routing key," and "path." These alternative names represent the same underlying concept of organizing and transmitting messages between producers and consumers. - -Here's an example of how to define channels: - -```yml -channels: - user/signedup: - subscribe: - message: - $ref: '#/components/messages/UserSignedUp' -``` - -In this example, `user/signedup` is the channel. This means that the application allows consumers to subscribe to the `user/signedup` channel to receive userSignUp messages. - -```mermaid -graph LR - subgraph Producer - p1(Producers) - end - - subgraph Channels - c1{user/signedup} - end - - subgraph Consumer - s1(Subscribers) - end - - subgraph Messages - m1($ref: '#/components/messages/UserSignedUp') - end - - p1 --> c1 - c1 --> s1 - s1 --> m1 -``` - -The diagram above represents the flow of communication between producers, channels, consumers, and messages. Producers generate messages, which are transmitted through the `user/signedup` channel and received by subscribing consumers. The actual data being transmitted is specified as `$ref: '#/components/messages/UserSignedUp'`. - -## Channel Server Relationship - -Channels and servers have a close relationship in asynchronous messaging systems. Channels act as communication pathways for messages, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on their purpose or topic. Servers, acting as producers, generate messages and publish them to specific channels. Consumers, including servers, subscribe to channels to receive the messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. - -```mermaid -graph TD - subgraph Servers - s1(Servers) - s2(Servers) - end - - subgraph Channels - c1{Channels} - end - - s1 --> c1 - s2 --> c1 - c1 --> s1 - c1 --> s2 -``` - -Here's an example on how channels and servers can be intertwined: - -```yml -asyncapi: 3.0.0 -info: - title: User Signup API - version: '1.0.0' -channels: - user/signedup: - subscribe: - summary: Subscribes to user signup events - message: - $ref: '#/components/messages/UserSignedUp' - -``` - -The example demonstrates a channel named `user/signedup` where clients can subscribe to receive user signup events, establishing a communication pathway between the server and the clients for notifying them about user signup events. - -## Channel Availability on Specific Servers - -In a distributed messaging system, a channel can be designed to be available on all servers. This means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. - -```mermaid -graph TD - subgraph Clients - c1(Client 1) - c2(Client 2) - c3(Client 3) - end - - subgraph Servers - s1(Server 1) - s2(Server 2) - s3(Server 3) - end - - subgraph Channel - ch(Channel) - end - - c1 --- ch - c2 --- ch - c3 --- ch - - s1 --- ch - s2 --- ch - s3 --- ch -``` - -Here is an example of how you might specify that a channel is available only on certain servers: - -```yml -channels: - user/signedup: - subscribe: - summary: Subscribes to user signup events - message: - $ref: '#/components/messages/UserSignedUp' - -servers: - serverA: - url: serverA.example.com - serverB: - url: serverB.example.com -``` - -In this code code defines a channel `user/signedup` for subscribing to user signup events, and two servers `Server A` and `Server B` with their respective URLs, enabling clients to receive user signup notifications from either server. - -So, when one specify a channel and servers, it allows the AsyncAPI document to clarify where each channel can be found. This is particularly beneficial in complex systems where different servers might be responsible for different sets of operations. - -## Multiple Channels in Single Server - -Having multiple channels in one server allows for better organization and management of different types of events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to subscribe to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. - -```mermaid -graph TD - subgraph Server - s1(Server) - end - - subgraph Channels - c1{Channel 1} - c2{Channel 2} - c3{Channel 3} - end - - s1 --> c1 - s1 --> c2 - s1 --> c3 -``` - -Here is an example of multiple channels are available on certain servers: - -```yml -channels: - user/signedup: - subscribe: - summary: Subscribes to user signup events - message: - $ref: '#/components/messages/UserSignedUp' - user/activated: - subscribe: - summary: Subscribes to user activation events - message: - $ref: '#/components/messages/UserActivated' - -servers: - serverA: - url: serverA.example.com - -``` - -The YAML code defines multiple channels, `user/signedup` and `user/activated`, within the `serverA` server, enabling clients to subscribe and receive events for user signup and activation. From fa6f240f170895ece6f1a78db0dcaa9a1762f411 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 2 Aug 2023 07:43:31 +0600 Subject: [PATCH 6/8] update weight --- pages/docs/concepts/asyncapi-document/_section.md | 2 +- pages/docs/concepts/asyncapi-document/adding-channels.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/_section.md b/pages/docs/concepts/asyncapi-document/_section.md index dc0a53d07ea..d7dea824ae2 100644 --- a/pages/docs/concepts/asyncapi-document/_section.md +++ b/pages/docs/concepts/asyncapi-document/_section.md @@ -1,4 +1,4 @@ --- title: 'AsyncAPI Document' -weight: 0 +weight: 50 --- \ No newline at end of file diff --git a/pages/docs/concepts/asyncapi-document/adding-channels.md b/pages/docs/concepts/asyncapi-document/adding-channels.md index 348b2324594..261c2b22de7 100644 --- a/pages/docs/concepts/asyncapi-document/adding-channels.md +++ b/pages/docs/concepts/asyncapi-document/adding-channels.md @@ -1,12 +1,12 @@ --- title: Adding Channels -weight: 200 +weight: 60 --- Adding [channels](../channel.md) in AsyncAPI specification allows organizing and categorizing messages, routing messages to the appropriate consumers, decoupling producers and consumers, scaling and extending the API, and providing clear documentation and communication about API's communication patterns. Additionally, alternative names for channels can be user-defined to suit specific context and preferences. ```mermaid -graph TD +graph LR A[AsyncAPI Specification] B[Channels] C[Organizing and Categorizing Messages] From 65fb8f259cd54a8741717e05189a004846f6c17e Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 21 Aug 2023 11:00:11 +0600 Subject: [PATCH 7/8] updating as per alejandra's requirement --- .../asyncapi-document/adding-channels.md | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-channels.md b/pages/docs/concepts/asyncapi-document/adding-channels.md index 261c2b22de7..b6c6ca1dad8 100644 --- a/pages/docs/concepts/asyncapi-document/adding-channels.md +++ b/pages/docs/concepts/asyncapi-document/adding-channels.md @@ -5,6 +5,8 @@ weight: 60 Adding [channels](../channel.md) in AsyncAPI specification allows organizing and categorizing messages, routing messages to the appropriate consumers, decoupling producers and consumers, scaling and extending the API, and providing clear documentation and communication about API's communication patterns. Additionally, alternative names for channels can be user-defined to suit specific context and preferences. +Here is a flowchart to describe adding channels: + ```mermaid graph LR A[AsyncAPI Specification] @@ -31,24 +33,21 @@ The diagram above represents the flow of communication between producers, channe Here is an example of how to define channels: ```yml -asyncapi: 3.0.0 -info: - title: Channel Example - version: 0.1.0 -channels: - userSignedUp: - address: user/signedup - messages: - userSignedUp: - description: An event describing that a user just signed up. +userSignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' ``` -This AsyncAPI specification sets up an interface for a `userSignedUp` channel, where the `address` field holds the actual address of the channel (`user/signedup`). +This AsyncAPI specification sets up an interface for a `userSignedUp` channel, where the `address` field holds the actual address of the channel (`user.signedup`). ## Channel Server Relationship Channels and [servers](../server.md) have a close relationship in asynchronous messaging systems. Channels act as message communication pathways, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on purpose or topic. Acting as producers, Servers generate messages and publish them to specific channels. Consumers, including servers, send to channels to receive messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. +Here is a flowchart to show the relationship between channels and servers: + ```mermaid graph TD subgraph Servers @@ -68,10 +67,14 @@ graph TD c1 --> s2 ``` +In this flowchart, channels serve as communication pathways, receiving messages from servers and routing them to consumers, while servers generate and publish messages to these channels. + ### Channel Availability on Specific Servers A channel can be designed to be available on all servers, which means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. +Here is a flowchart showing a channel is available on multiple servers and accessible by multiple clients: + ```mermaid graph TD subgraph Clients @@ -101,6 +104,8 @@ graph TD s3 --- ch ``` +In the above flowchart, messages published to the channel to reach all connected clients, regardless of their server connection. + Here is an example of how you might specify that a channel is available only on specific servers: ```yml @@ -125,6 +130,8 @@ Specifying a channel and servers allows the AsyncAPI document to clarify where e Having multiple channels in one server allows for better organization and management of different events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to send to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. +Here is a diagram showing a single server hosting multiple channels: + ```mermaid graph TD subgraph Server @@ -146,6 +153,8 @@ graph TD s1 --> c3 ``` +Hosting multiple channels in single server allows user to organize and manage better in case for multiple events or messages by facilitating modular and scalable system architecture. + Here is an example of multiple channels available on specific servers: ```yml From 4f867ca97da199334556dc020ed31f370a2be975 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 5 Sep 2023 09:48:09 +0600 Subject: [PATCH 8/8] editorial fix --- .../asyncapi-document/adding-channels.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-channels.md b/pages/docs/concepts/asyncapi-document/adding-channels.md index b6c6ca1dad8..882efcb530e 100644 --- a/pages/docs/concepts/asyncapi-document/adding-channels.md +++ b/pages/docs/concepts/asyncapi-document/adding-channels.md @@ -3,9 +3,9 @@ title: Adding Channels weight: 60 --- -Adding [channels](../channel.md) in AsyncAPI specification allows organizing and categorizing messages, routing messages to the appropriate consumers, decoupling producers and consumers, scaling and extending the API, and providing clear documentation and communication about API's communication patterns. Additionally, alternative names for channels can be user-defined to suit specific context and preferences. +Adding [channels](../channel) in AsyncAPI specification allows organizing and categorizing messages, routing messages to the appropriate consumers, decoupling producers and consumers, scaling and extending the API, and providing clear documentation and communication about API's communication patterns. Additionally, alternative names for channels can be user-defined to suit specific context and preferences. -Here is a flowchart to describe adding channels: +Here is a diagram to describe adding channels: ```mermaid graph LR @@ -42,11 +42,11 @@ userSignedUp: This AsyncAPI specification sets up an interface for a `userSignedUp` channel, where the `address` field holds the actual address of the channel (`user.signedup`). -## Channel Server Relationship +## Channel server relationship -Channels and [servers](../server.md) have a close relationship in asynchronous messaging systems. Channels act as message communication pathways, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on purpose or topic. Acting as producers, Servers generate messages and publish them to specific channels. Consumers, including servers, send to channels to receive messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. +Channels and [servers](../server) have a close relationship in asynchronous messaging systems. Channels act as message communication pathways, while servers generate and publish messages to these channels. Channels serve as logical destinations where messages are organized based on purpose or topic. Acting as producers, Servers generate messages and publish them to specific channels. Consumers, including servers, send to channels to receive messages. Channels ensure that messages are routed to the appropriate consumers based on their subscriptions. This relationship between channels and servers forms the foundation for building scalable and flexible messaging systems. -Here is a flowchart to show the relationship between channels and servers: +Here is a diagram to show the relationship between channels and servers: ```mermaid graph TD @@ -67,13 +67,13 @@ graph TD c1 --> s2 ``` -In this flowchart, channels serve as communication pathways, receiving messages from servers and routing them to consumers, while servers generate and publish messages to these channels. +In this diagram, channels serve as communication pathways, receiving messages from servers and routing them to consumers, while servers generate and publish messages to these channels. -### Channel Availability on Specific Servers +### Channel availability on specific servers A channel can be designed to be available on all servers, which means that the channel is globally accessible, allowing messages published to it to reach all connected clients, regardless of their server connection. -Here is a flowchart showing a channel is available on multiple servers and accessible by multiple clients: +Here is a diagram showing a channel is available on multiple servers and accessible by multiple clients: ```mermaid graph TD @@ -104,7 +104,7 @@ graph TD s3 --- ch ``` -In the above flowchart, messages published to the channel to reach all connected clients, regardless of their server connection. +In the above diagram, messages published to the channel to reach all connected clients, regardless of their server connection. Here is an example of how you might specify that a channel is available only on specific servers: @@ -126,7 +126,7 @@ The above code defines a channel `user/signedup` for subscribing to user signup Specifying a channel and servers allows the AsyncAPI document to clarify where each channel can be found. This method is particularly beneficial in complex systems where different servers might be responsible for different operations. -### Multiple Channels in Single Server +### Multiple channels in single server Having multiple channels in one server allows for better organization and management of different events or messages within the same server instance, providing a more modular and scalable architecture for handling various functionalities. It enables clients to send to specific channels based on their interests or requirements, ensuring efficient message delivery and reducing complexity in the overall system design. @@ -176,4 +176,4 @@ servers: The YAML code defines multiple channels, `user/signedup` and `user/activated`, within the `serverA` server, enabling clients to subscribe and receive user signup and activation events. -To know more details on how to add server check [add servers](add-server.md). +To know more details on how to add server check [add servers](add-server).