From b1a4c146931a0729640a055e36afd026bfd1ff03 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 17 Jul 2023 20:15:45 +0600 Subject: [PATCH 1/8] adding dynamic channel page --- .../concepts/asyncapi-document/_section.md | 4 + .../dynamic_channel_names.md | 117 ++++++++++++++++++ 2 files changed, 121 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/_section.md create mode 100644 pages/docs/concepts/asyncapi-document/dynamic_channel_names.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/dynamic_channel_names.md b/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md new file mode 100644 index 00000000000..6bafcc58699 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md @@ -0,0 +1,117 @@ +--- +title: Dynamic Channel Names +weight: 220 +--- + +In AsyncAPI, dynamic parts of a channel name can be specified using parameters. These parameters are typically defined in the components section of AsyncAPI document. They can be used throughout the document and specifically, they can be referenced in the channels section to denote dynamic parts of channel names. + +```mermaid +graph TD + subgraph Components + p(Parameters) + end + + subgraph Channels + c1{Channel 1} + c2{Channel 2} + c3{Channel 3} + end + + p --> c1 + p --> c2 + p --> c3 +``` + +To understand the concept better, let's consider an example where we are modeling a `UserSignedUp` event. This event would involve a channel name like `user/{userId}/signedup`. Here, `{userId}` is a dynamic part, which will vary depending on which user has signed up. You want to define this `{userId}` part as a parameter - + +```yml +components: + parameters: + userId: + description: The ID of the user. + schema: + type: string +``` + +The `userId` parameter is defined in the components section under parameters. + +Next, this parameter can be used in the channels section to form the dynamic part of a channel name. It is done using its reference ($ref) - + +```yml +channels: + user/{userId}/signedup: + parameters: + userId: + $ref: '#/components/parameters/userId' + publish: + message: + $ref: '#/components/messages/UserSignedUp' +``` + +In the above AsyncAPI document, the `user/{userId}/signedup` channel is publishing a `UserSignedUp` message. The `{userId}` in the channel name is replaced dynamically at runtime by the specific ID of the user who signed up. + +## Parameter Context + +In AsyncAPI, the context of parameters in channel names often refers to where the parameter value comes from. For example, the parameter might be populated from the runtime event payload. This context can be noted in the AsyncAPI document, and it can be used by code generators to make the developer experience easier. + +```mermaid +graph LR + subgraph RuntimeEvent + e(Event) + end + + subgraph Parameters + p(Parameter) + end + + subgraph Channel + c{Channel} + end + + e --> p + p --> c +``` + +Here is an example for parameter context - + +```yml +channels: + user/{userId}/signup: + parameters: + userId: + description: "Id of the user." + context: "payload" + schema: + type: "string" + subscribe: + message: + $ref: "#/components/messages/UserSignedUp" +``` + +In this example, the `userId` parameter in the channel name `user/{userId}/signup` is populated from the payload of the UserSignedUp event. The (context: "payload") line indicates this. + +## Reusing Parameters + +An important thing about parameters is that they can be reused. If there is another event, for example, a `UserUpdated` event, which also requires the userId, the parameter can be reused like following example - + +```yml +channels: + user/{userId}/signedup: + parameters: + userId: + $ref: '#/components/parameters/userId' + publish: + message: + $ref: '#/components/messages/UserSignedUp' + user/{userId}/updated: + parameters: + userId: + $ref: '#/components/parameters/userId' + subscribe: + message: + $ref: '#/components/messages/UserUpdated' +``` + +In this code, the previously defined userId parameter is reused to form the channel name for `UserUpdated` event. + +Defining and reusing parameters in this way can make your API definition cleaner, more maintainable, and less likely to contain errors. From cd7eff7ff2cd7baa4bc6b9772e61d246ea4dbd9e Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 18 Jul 2023 15:44:21 +0600 Subject: [PATCH 2/8] update code --- .../dynamic_channel_names.md | 24 ++++++++++++------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md b/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md index 6bafcc58699..3e41ac9595f 100644 --- a/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md +++ b/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md @@ -75,17 +75,25 @@ graph LR Here is an example for parameter context - ```yml +asyncapi: 3.0.0 +info: + title: Cool Example + vesion: 0.1.0 + channels: - user/{userId}/signup: - parameters: - userId: + userSignedUp: + address: user/{userId}/signup + messages: + userSignedUp: description: "Id of the user." - context: "payload" - schema: + payload: type: "string" - subscribe: - message: - $ref: "#/components/messages/UserSignedUp" + +operations: + userSignedUp: + action: send + channel: + $ref: '#/channels/userSignedUp' ``` In this example, the `userId` parameter in the channel name `user/{userId}/signup` is populated from the payload of the UserSignedUp event. The (context: "payload") line indicates this. From 0d8834845f83c84107fb1463eadef8c175ba1790 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Mon, 24 Jul 2023 20:23:59 +0600 Subject: [PATCH 3/8] updating as per review --- .../dynamic-channel-names.md | 93 +++++++++++++ .../dynamic_channel_names.md | 125 ------------------ 2 files changed, 93 insertions(+), 125 deletions(-) create mode 100644 pages/docs/concepts/asyncapi-document/dynamic-channel-names.md delete mode 100644 pages/docs/concepts/asyncapi-document/dynamic_channel_names.md diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md new file mode 100644 index 00000000000..4da2de03a60 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md @@ -0,0 +1,93 @@ +--- +title: Dynamic Channel Names +weight: 220 +--- + +Dynamic channel names, also known as channel address expressions, are a key feature of AsyncAPI. Dynamic channel names in AsyncAPI are pivotal for enhancing the flexibility, interoperability, reusability, and standardization of asynchronous APIs. They allow for variable usage in channel names that can be adapted to multiple APIs, used across different protocols, and reused across channels, thus preventing redundancy and maintaining consistency. This adaptability to different APIs aids in creating a unified view of the API, making it easier to comprehend and utilize. Dynamic channel names contribute to code and documentation generation and event management tooling, thereby improving APIs' overall efficiency and usability. + +```mermaid +flowchart TD + subgraph "Dynamic Channel Names" + A[Key Feature] --> B[Enhanced Flexibility] + A --> C[Improved Interoperability] + A --> D[Increased Reusability] + A --> E[Promotes Standardization] + end + subgraph "Benefits" + B --> F[Adaptable to Multiple APIs] + B --> G[Supports Different Protocols] + D --> H[Prevents Redundancy] + D --> I[Maintains Consistency] + F --> J[Unified API View] + F --> K[Easier Comprehension and Utilization] + end + subgraph "Contributions" + H --> L[Code and Documentation Generation] + I --> M[Event Management Tooling] + J --> N[Improved API Efficiency] + K --> O[Enhanced API Usability] + end +``` + +## Parameter Context + +The Parameter Context clarifies the origin of parameters, ensuring consistent understanding across teams. It also enables efficient code generation, thereby accelerating development and enhancing the developer experience. + +In AsyncAPI, the context of parameters in channel names often refers to where the parameter value comes from. For example, the parameter might be populated from the runtime event payload. This context can be noted in the AsyncAPI document, and code generators can use it to make the developer experience easier. + +```mermaid +flowchart TB + subgraph "AsyncAPI Specification" + A[Channel Names] --> B[Parameters] + B --> C[Parameter Context] + end + subgraph "Parameter Context" + C --> D[Indicate the origin of parameter value] + C --> E[Help code generators enhance developer experience] + end + subgraph "Parameter Sources" + D --> F[Runtime Event Payload] + D --> G[Other possible sources] + end + +``` + +Here is an example of parameter context: + +```yml +address: user/{userId}/signedup +parameters: + userId: + description: Id of the user. +``` + +## Reusing Parameters + +An important thing about parameters is that they can be reused. If there is another event, for example, a `UserUpdated` event, which also requires the userId, the parameter can be reused like the following example: + +```yml +asyncapi: 3.0.0 +info: + title: Cool Example + version: 0.1.0 +channels: + userSignedUp: + address: user/{userId}/signedup + parameters: + userId: + description: Id of the user. + location: $message.payload#/userid + parameters: + userId: + description: Id of the user. + location: $message.payload#/UserUpdated +operations: + userSignedUp: + action: receive + channel: + $ref: '#/channels/userSignedUp' +``` + +In this code, the previously defined userId parameter is reused to form the channel name for `UserUpdated` event. + +Defining and reusing parameters in this way can make your API definition cleaner, more maintainable, and less likely to contain errors. diff --git a/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md b/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md deleted file mode 100644 index 3e41ac9595f..00000000000 --- a/pages/docs/concepts/asyncapi-document/dynamic_channel_names.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Dynamic Channel Names -weight: 220 ---- - -In AsyncAPI, dynamic parts of a channel name can be specified using parameters. These parameters are typically defined in the components section of AsyncAPI document. They can be used throughout the document and specifically, they can be referenced in the channels section to denote dynamic parts of channel names. - -```mermaid -graph TD - subgraph Components - p(Parameters) - end - - subgraph Channels - c1{Channel 1} - c2{Channel 2} - c3{Channel 3} - end - - p --> c1 - p --> c2 - p --> c3 -``` - -To understand the concept better, let's consider an example where we are modeling a `UserSignedUp` event. This event would involve a channel name like `user/{userId}/signedup`. Here, `{userId}` is a dynamic part, which will vary depending on which user has signed up. You want to define this `{userId}` part as a parameter - - -```yml -components: - parameters: - userId: - description: The ID of the user. - schema: - type: string -``` - -The `userId` parameter is defined in the components section under parameters. - -Next, this parameter can be used in the channels section to form the dynamic part of a channel name. It is done using its reference ($ref) - - -```yml -channels: - user/{userId}/signedup: - parameters: - userId: - $ref: '#/components/parameters/userId' - publish: - message: - $ref: '#/components/messages/UserSignedUp' -``` - -In the above AsyncAPI document, the `user/{userId}/signedup` channel is publishing a `UserSignedUp` message. The `{userId}` in the channel name is replaced dynamically at runtime by the specific ID of the user who signed up. - -## Parameter Context - -In AsyncAPI, the context of parameters in channel names often refers to where the parameter value comes from. For example, the parameter might be populated from the runtime event payload. This context can be noted in the AsyncAPI document, and it can be used by code generators to make the developer experience easier. - -```mermaid -graph LR - subgraph RuntimeEvent - e(Event) - end - - subgraph Parameters - p(Parameter) - end - - subgraph Channel - c{Channel} - end - - e --> p - p --> c -``` - -Here is an example for parameter context - - -```yml -asyncapi: 3.0.0 -info: - title: Cool Example - vesion: 0.1.0 - -channels: - userSignedUp: - address: user/{userId}/signup - messages: - userSignedUp: - description: "Id of the user." - payload: - type: "string" - -operations: - userSignedUp: - action: send - channel: - $ref: '#/channels/userSignedUp' -``` - -In this example, the `userId` parameter in the channel name `user/{userId}/signup` is populated from the payload of the UserSignedUp event. The (context: "payload") line indicates this. - -## Reusing Parameters - -An important thing about parameters is that they can be reused. If there is another event, for example, a `UserUpdated` event, which also requires the userId, the parameter can be reused like following example - - -```yml -channels: - user/{userId}/signedup: - parameters: - userId: - $ref: '#/components/parameters/userId' - publish: - message: - $ref: '#/components/messages/UserSignedUp' - user/{userId}/updated: - parameters: - userId: - $ref: '#/components/parameters/userId' - subscribe: - message: - $ref: '#/components/messages/UserUpdated' -``` - -In this code, the previously defined userId parameter is reused to form the channel name for `UserUpdated` event. - -Defining and reusing parameters in this way can make your API definition cleaner, more maintainable, and less likely to contain errors. From 9dcf3070200e31a490ba36ccd61e54ff7025ae99 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Wed, 2 Aug 2023 07:50:44 +0600 Subject: [PATCH 4/8] update weight --- .../concepts/asyncapi-document/_section.md | 2 +- .../dynamic-channel-names.md | 45 ++++++++----------- 2 files changed, 19 insertions(+), 28 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/dynamic-channel-names.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md index 4da2de03a60..7ca4804c4d8 100644 --- a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md @@ -1,32 +1,24 @@ --- title: Dynamic Channel Names -weight: 220 +weight: 80 --- Dynamic channel names, also known as channel address expressions, are a key feature of AsyncAPI. Dynamic channel names in AsyncAPI are pivotal for enhancing the flexibility, interoperability, reusability, and standardization of asynchronous APIs. They allow for variable usage in channel names that can be adapted to multiple APIs, used across different protocols, and reused across channels, thus preventing redundancy and maintaining consistency. This adaptability to different APIs aids in creating a unified view of the API, making it easier to comprehend and utilize. Dynamic channel names contribute to code and documentation generation and event management tooling, thereby improving APIs' overall efficiency and usability. ```mermaid -flowchart TD - subgraph "Dynamic Channel Names" - A[Key Feature] --> B[Enhanced Flexibility] - A --> C[Improved Interoperability] - A --> D[Increased Reusability] - A --> E[Promotes Standardization] - end - subgraph "Benefits" - B --> F[Adaptable to Multiple APIs] - B --> G[Supports Different Protocols] - D --> H[Prevents Redundancy] - D --> I[Maintains Consistency] - F --> J[Unified API View] - F --> K[Easier Comprehension and Utilization] - end - subgraph "Contributions" - H --> L[Code and Documentation Generation] - I --> M[Event Management Tooling] - J --> N[Improved API Efficiency] - K --> O[Enhanced API Usability] - end +graph TD +A[AsyncAPI] +B[Dynamic Channel Names] +D[Variable Usage in Channel Names] +E[Adapted to Multiple APIs and Protocols] +F[Reused Across Channels] + +style B fill:#47BCEE,stroke:#47BCEE; + +A --> B +B --> D +D --> E +D --> F ``` ## Parameter Context @@ -40,6 +32,9 @@ flowchart TB subgraph "AsyncAPI Specification" A[Channel Names] --> B[Parameters] B --> C[Parameter Context] + + style C fill:#47BCEE,stroke:#47BCEE; + end subgraph "Parameter Context" C --> D[Indicate the origin of parameter value] @@ -58,7 +53,7 @@ Here is an example of parameter context: address: user/{userId}/signedup parameters: userId: - description: Id of the user. + description: Id of the user ``` ## Reusing Parameters @@ -66,10 +61,6 @@ parameters: An important thing about parameters is that they can be reused. If there is another event, for example, a `UserUpdated` event, which also requires the userId, the parameter can be reused like the following example: ```yml -asyncapi: 3.0.0 -info: - title: Cool Example - version: 0.1.0 channels: userSignedUp: address: user/{userId}/signedup From e6f2c0ed01fa9733d8b45e761502f06ba4589873 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sat, 5 Aug 2023 18:50:13 +0600 Subject: [PATCH 5/8] Updated except the file name I will change the file name later as if I change it now, all reviews which I havent fixed yet, are gonna be outdated. --- .../dynamic-channel-names.md | 24 +++++++++---------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md index 7ca4804c4d8..c85ec013280 100644 --- a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md @@ -1,15 +1,15 @@ --- -title: Dynamic Channel Names +title: Dynamic Channel Address weight: 80 --- -Dynamic channel names, also known as channel address expressions, are a key feature of AsyncAPI. Dynamic channel names in AsyncAPI are pivotal for enhancing the flexibility, interoperability, reusability, and standardization of asynchronous APIs. They allow for variable usage in channel names that can be adapted to multiple APIs, used across different protocols, and reused across channels, thus preventing redundancy and maintaining consistency. This adaptability to different APIs aids in creating a unified view of the API, making it easier to comprehend and utilize. Dynamic channel names contribute to code and documentation generation and event management tooling, thereby improving APIs' overall efficiency and usability. +Dynamic channel address in AsyncAPI provide flexibility, reusability, and standardization in asynchronous APIs. They allow for the use of variable values in channel address, enabling the creation of parameterized channel templates. This feature has real-world use cases such as supporting API versioning, facilitating multi-tenancy, and enabling event filtering and routing. By incorporating dynamic channel address, developers can enhance the scalability, personalization, and efficiency of their APIs. ```mermaid graph TD A[AsyncAPI] -B[Dynamic Channel Names] -D[Variable Usage in Channel Names] +B[Dynamic Channel Address] +D[Variable Usage in Channel Address] E[Adapted to Multiple APIs and Protocols] F[Reused Across Channels] @@ -23,14 +23,12 @@ D --> F ## Parameter Context -The Parameter Context clarifies the origin of parameters, ensuring consistent understanding across teams. It also enables efficient code generation, thereby accelerating development and enhancing the developer experience. - -In AsyncAPI, the context of parameters in channel names often refers to where the parameter value comes from. For example, the parameter might be populated from the runtime event payload. This context can be noted in the AsyncAPI document, and code generators can use it to make the developer experience easier. +The parameter context in AsyncAPI clarifies the origin of parameters, ensuring consistent understanding across teams. It enables efficient code generation, accelerating development and enhancing the developer experience. By noting the context in the AsyncAPI document, code generators can simplify the developer experience by automatically handling parameter values. ```mermaid flowchart TB subgraph "AsyncAPI Specification" - A[Channel Names] --> B[Parameters] + A[Channel Address] --> B[Parameters] B --> C[Parameter Context] style C fill:#47BCEE,stroke:#47BCEE; @@ -50,7 +48,7 @@ flowchart TB Here is an example of parameter context: ```yml -address: user/{userId}/signedup +address: 'user/{userId}/signedup' parameters: userId: description: Id of the user @@ -58,16 +56,16 @@ parameters: ## Reusing Parameters -An important thing about parameters is that they can be reused. If there is another event, for example, a `UserUpdated` event, which also requires the userId, the parameter can be reused like the following example: +An important thing about parameters is that they can be reused. If there is another message, for example, a `UserUpdated` message, which also requires the userId, the parameter can be reused like the following example: ```yml channels: userSignedUp: - address: user/{userId}/signedup + address: 'user/{userId}/signedup' parameters: userId: description: Id of the user. - location: $message.payload#/userid + location: '$message.payload#/userid' parameters: userId: description: Id of the user. @@ -79,6 +77,6 @@ operations: $ref: '#/channels/userSignedUp' ``` -In this code, the previously defined userId parameter is reused to form the channel name for `UserUpdated` event. +In this AsyncAPI document, the previously defined userId parameter is reused to form the channel address for `UserUpdated` event. Defining and reusing parameters in this way can make your API definition cleaner, more maintainable, and less likely to contain errors. From fbd3da876fd32935de7a1ccb101e326867a6bfc6 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Sat, 26 Aug 2023 10:05:54 +0600 Subject: [PATCH 6/8] updating as per review --- .../dynamic-channel-address.md | 120 ++++++++++++++++++ .../dynamic-channel-names.md | 82 ------------ 2 files changed, 120 insertions(+), 82 deletions(-) create mode 100644 pages/docs/concepts/asyncapi-document/dynamic-channel-address.md delete mode 100644 pages/docs/concepts/asyncapi-document/dynamic-channel-names.md diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md new file mode 100644 index 00000000000..55ef7e97675 --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md @@ -0,0 +1,120 @@ +--- +title: Dynamic Channel Address +weight: 80 +--- + +Dynamic channel addresses are used to specify dynamic parts of a channel name, which becomes particularly useful when you want to use and reuse parameters in the channel name. It provides flexibility in how you structure your event-driven interfaces. + +Here is the diagram explaining dynamic channel address: + +```mermaid +graph TD +A[AsyncAPI] +B[Dynamic Channel Address] +D[Variable Usage in Channel Address] +E[Adapted to Multiple APIs and Protocols] +F[Reused Across Channels] + +style B fill:#47BCEE,stroke:#47BCEE; + +A --> B +B --> D +D --> E +D --> F +``` + +The flowchart shows how dynamic channel addresses allow flexible event-driven interfaces by using and reusing parameters in channel names, adapting well to various APIs and protocols. + +Here is an example of dynamic channel address: + +```yml +userSignedUp: + address: 'user.signedup' + messages: + userSignedUp: + $ref: '#/components/messages/userSignedUp' +``` + +This document defines a dynamic channel address for a `userSignedUp` event message, making it easy to include and reuse specific details in the channel address. + +## Parameter Context + +In a channel address, there's a map of parameters. This map needs to include all the same parameters that are in the main channel address. The names you use for the parameters in this map must be exactly the same as the names you used in the channel address. + +```mermaid +graph TD + A[Channel Address] --> B{Parameter Map} + B --> C{Parameters} + C --> D[Parameter 1] + C --> E[Parameter 2] + C --> F[Parameter 3] + D --> G{Parameter Name} + E --> G + F --> G + A --> G + + +style B fill:#47BCEE,stroke:#47BCEE; +``` + +This diagram shows how the channel address includes the same parameters as the channel address, and each parameter's name matches the one used in the address. + +Here is an example of parameter context: + +```yml +address: `user/{userId}/signedup` +parameters: + userId: + description: Id of the user. +``` + +In the above document, `user/{userId}/signedup` is the endpoint where `{userId}` is a path parameter. + +## Reusing Parameters + +Parameters can be reused. This reuse optimizes the usage of parameters within the event-driven interface by letting you use the parameters again. If there is another message, for example, a `UserUpdated` message, which also requires the `userId`, the parameter can be reused like the following following diagram: + +```mermaid +graph TD + subgraph Channels + userSignedUp["userSignedUp"] + end + + subgraph Parameters + userId["userId"] + end + + userSignedUp -->|requires| userId + + subgraph Reused Parameters + UserUpdated["UserUpdated"] + style UserUpdated fill:#47BCEE,stroke:#47BCEE; + + end + UserUpdated -->|reuses| userId + + +``` + +In this diagram, a channel named `userSignedUp` that requires a parameter `userId` .Additionally, the parameter `userId` is reused for another message, `UserUpdated`. + +Here is a code of reusing parameters: + +```yml +channels: + userSignedUp: + address: 'user/{userId}/signedup' + parameters: + userId: + description: Id of the user. + parameters: + userId: + description: Id of the user. +operations: + userSignedUp: + action: receive + channel: + $ref: '#/channels/userSignedUp' +``` + +In this AsyncAPI document, the previously defined `userId` parameter is reused to form the channel address for `UserUpdated` message. diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md deleted file mode 100644 index c85ec013280..00000000000 --- a/pages/docs/concepts/asyncapi-document/dynamic-channel-names.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Dynamic Channel Address -weight: 80 ---- - -Dynamic channel address in AsyncAPI provide flexibility, reusability, and standardization in asynchronous APIs. They allow for the use of variable values in channel address, enabling the creation of parameterized channel templates. This feature has real-world use cases such as supporting API versioning, facilitating multi-tenancy, and enabling event filtering and routing. By incorporating dynamic channel address, developers can enhance the scalability, personalization, and efficiency of their APIs. - -```mermaid -graph TD -A[AsyncAPI] -B[Dynamic Channel Address] -D[Variable Usage in Channel Address] -E[Adapted to Multiple APIs and Protocols] -F[Reused Across Channels] - -style B fill:#47BCEE,stroke:#47BCEE; - -A --> B -B --> D -D --> E -D --> F -``` - -## Parameter Context - -The parameter context in AsyncAPI clarifies the origin of parameters, ensuring consistent understanding across teams. It enables efficient code generation, accelerating development and enhancing the developer experience. By noting the context in the AsyncAPI document, code generators can simplify the developer experience by automatically handling parameter values. - -```mermaid -flowchart TB - subgraph "AsyncAPI Specification" - A[Channel Address] --> B[Parameters] - B --> C[Parameter Context] - - style C fill:#47BCEE,stroke:#47BCEE; - - end - subgraph "Parameter Context" - C --> D[Indicate the origin of parameter value] - C --> E[Help code generators enhance developer experience] - end - subgraph "Parameter Sources" - D --> F[Runtime Event Payload] - D --> G[Other possible sources] - end - -``` - -Here is an example of parameter context: - -```yml -address: 'user/{userId}/signedup' -parameters: - userId: - description: Id of the user -``` - -## Reusing Parameters - -An important thing about parameters is that they can be reused. If there is another message, for example, a `UserUpdated` message, which also requires the userId, the parameter can be reused like the following example: - -```yml -channels: - userSignedUp: - address: 'user/{userId}/signedup' - parameters: - userId: - description: Id of the user. - location: '$message.payload#/userid' - parameters: - userId: - description: Id of the user. - location: $message.payload#/UserUpdated -operations: - userSignedUp: - action: receive - channel: - $ref: '#/channels/userSignedUp' -``` - -In this AsyncAPI document, the previously defined userId parameter is reused to form the channel address for `UserUpdated` event. - -Defining and reusing parameters in this way can make your API definition cleaner, more maintainable, and less likely to contain errors. From 40f961bc5fb9d2d0dfb8fd8e82be715620a0e989 Mon Sep 17 00:00:00 2001 From: Mahfuza Date: Tue, 5 Sep 2023 10:28:42 +0600 Subject: [PATCH 7/8] update as per review --- .../dynamic-channel-address.md | 63 ++++++++++--------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md index 55ef7e97675..452f44e7442 100644 --- a/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md @@ -8,22 +8,22 @@ Dynamic channel addresses are used to specify dynamic parts of a channel name, w Here is the diagram explaining dynamic channel address: ```mermaid -graph TD -A[AsyncAPI] -B[Dynamic Channel Address] -D[Variable Usage in Channel Address] -E[Adapted to Multiple APIs and Protocols] -F[Reused Across Channels] - -style B fill:#47BCEE,stroke:#47BCEE; - -A --> B -B --> D -D --> E -D --> F + graph TD + A[AsyncAPI] + B[Dynamic Channel Address] + D[Variable Usage in Channel Address] + E[Adapted to Multiple APIs and Protocols] + F[Reused Across Channels] + + style B fill:#47BCEE,stroke:#47BCEE; + + A --> B + B --> D + D --> E + D --> F ``` -The flowchart shows how dynamic channel addresses allow flexible event-driven interfaces by using and reusing parameters in channel names, adapting well to various APIs and protocols. +The diagram shows how dynamic channel addresses allow flexible event-driven interfaces by using and reusing parameters in channel names, adapting well to various APIs and protocols. Here is an example of dynamic channel address: @@ -37,9 +37,11 @@ userSignedUp: This document defines a dynamic channel address for a `userSignedUp` event message, making it easy to include and reuse specific details in the channel address. -## Parameter Context +## Parameter context + +In a channel address, there's a map of parameters, which needs to include all the same parameters that are in the main channel address. The names you use for the parameters in this map must be exactly the same as the names you used in the channel address. -In a channel address, there's a map of parameters. This map needs to include all the same parameters that are in the main channel address. The names you use for the parameters in this map must be exactly the same as the names you used in the channel address. +Here is a diagram explaining parameter context: ```mermaid graph TD @@ -53,8 +55,7 @@ graph TD F --> G A --> G - -style B fill:#47BCEE,stroke:#47BCEE; + style B fill:#47BCEE,stroke:#47BCEE; ``` This diagram shows how the channel address includes the same parameters as the channel address, and each parameter's name matches the one used in the address. @@ -62,17 +63,23 @@ This diagram shows how the channel address includes the same parameters as the c Here is an example of parameter context: ```yml -address: `user/{userId}/signedup` -parameters: - userId: - description: Id of the user. +user/{userId}/signup: + parameters: + userId: + description: Id of the user. + location: $message.payload#/user/id + subscribe: + message: + $ref: "#/components/messages/userSignedUp" ``` In the above document, `user/{userId}/signedup` is the endpoint where `{userId}` is a path parameter. -## Reusing Parameters +## Reusing parameters + +Parameters can be reused. This reuse optimizes the usage of parameters within the event-driven interface by letting you use the parameters again. -Parameters can be reused. This reuse optimizes the usage of parameters within the event-driven interface by letting you use the parameters again. If there is another message, for example, a `UserUpdated` message, which also requires the `userId`, the parameter can be reused like the following following diagram: +If there is another message, for example, a `UserUpdated` message, which also requires the `userId`, the parameter can be reused like the following following diagram: ```mermaid graph TD @@ -92,11 +99,9 @@ graph TD end UserUpdated -->|reuses| userId - - ``` -In this diagram, a channel named `userSignedUp` that requires a parameter `userId` .Additionally, the parameter `userId` is reused for another message, `UserUpdated`. +In this diagram, a channel named `userSignedUp` that requires a parameter `userId` .Additionally, the parameter `userId` is reused for another message, `UserUpdated`. Here is a code of reusing parameters: @@ -108,8 +113,8 @@ channels: userId: description: Id of the user. parameters: - userId: - description: Id of the user. + UserUpdated: + description: Updated Id of the user. operations: userSignedUp: action: receive From c92e10d1b2122ed18de2ee30c5a8be9c9d0e7d40 Mon Sep 17 00:00:00 2001 From: Mahfuza Humayra Mohona Date: Tue, 7 Nov 2023 11:10:16 +0600 Subject: [PATCH 8/8] update as per suggetion --- .../dynamic-channel-address.md | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md index 452f44e7442..9c19cfeb215 100644 --- a/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md +++ b/pages/docs/concepts/asyncapi-document/dynamic-channel-address.md @@ -3,7 +3,7 @@ title: Dynamic Channel Address weight: 80 --- -Dynamic channel addresses are used to specify dynamic parts of a channel name, which becomes particularly useful when you want to use and reuse parameters in the channel name. It provides flexibility in how you structure your event-driven interfaces. +Dynamic channel addresses specify dynamic parts of a channel address, which becomes particularly useful when you want to use and reuse parameters in a channel address. Here is the diagram explaining dynamic channel address: @@ -60,7 +60,7 @@ graph TD This diagram shows how the channel address includes the same parameters as the channel address, and each parameter's name matches the one used in the address. -Here is an example of parameter context: +Here is an example of a dynamic channel address and its parameter: ```yml user/{userId}/signup: @@ -73,13 +73,13 @@ user/{userId}/signup: $ref: "#/components/messages/userSignedUp" ``` -In the above document, `user/{userId}/signedup` is the endpoint where `{userId}` is a path parameter. +In the above document, `user/{userId}/signedup` is the address where `{userId}` is a parameter for that address. ## Reusing parameters -Parameters can be reused. This reuse optimizes the usage of parameters within the event-driven interface by letting you use the parameters again. +Parameters can be reused. This reuse optimizes the usage of parameters within the API by letting you use the parameters again. -If there is another message, for example, a `UserUpdated` message, which also requires the `userId`, the parameter can be reused like the following following diagram: +If there is another message, for example, a `UserUpdated` message, which also requires the `userId` parameter, it can be reused like in the following example: ```mermaid graph TD @@ -103,23 +103,22 @@ graph TD In this diagram, a channel named `userSignedUp` that requires a parameter `userId` .Additionally, the parameter `userId` is reused for another message, `UserUpdated`. -Here is a code of reusing parameters: +Here is an example of reusing parameters: ```yml channels: - userSignedUp: + UserSignedUp: address: 'user/{userId}/signedup' parameters: - userId: - description: Id of the user. + $ref: '#/components/parameters/userId' + UserUpdated: + address: 'user/{userId}/updated' parameters: - UserUpdated: - description: Updated Id of the user. -operations: - userSignedUp: - action: receive - channel: - $ref: '#/channels/userSignedUp' + $ref: '#/components/parameters/userId' +components: + parameters: + userId: + description: Id of the user. ``` -In this AsyncAPI document, the previously defined `userId` parameter is reused to form the channel address for `UserUpdated` message. +In the previous example, the `userId` parameter is defined under `components`, and both channels `UserSignedUp` and `UserUpdated` are reusing it in their address by referencing via `$ref`.