From 992b9f0fe0641d0dec12aa138ec36cec1291ea41 Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Thu, 7 Dec 2023 20:13:02 +0530 Subject: [PATCH 1/5] adding content about adding operations --- .../asyncapi-document/adding-operations.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 pages/docs/concepts/asyncapi-document/adding-operations.md diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md new file mode 100644 index 000000000000..e5f95257f21d --- /dev/null +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -0,0 +1,122 @@ +--- +title: Adding Operations +weight: 60 +--- + +In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. + +In a AsyncAPI document, Operations describe the behaviors and capabilities of the messaging channels described in the AsyncAPI document. In a messaging channel, an `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. + +## Defining Operations + +Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for their definition. More information about each field name that is used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). +Additionally, an example to show the usage of each field name in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). + +The following diagram briefs the some field names that are frequently used to define operations in a AsyncAPI document: + +```mermaid +graph LR +A[Required Fields] +B[Summary] +C[Action] +D[Optional Fields] +E[Description] +F[Channel] +G[Tags] +H[Bindings] +I[Traits] +A --> B +A --> C +D --> E +D --> F +D --> G +D --> H +D --> I +style A fill:#47BCEE,stroke:#000; +style D fill:#47BCEE,stroke:#000 +``` + +## Adding Operations + +`operations` are separate objects in the AsyncAPI document on the root level together with `channels` and other objects. +Operations must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: + +``` +onUserSignUp: + title: User sign up + summary: Action to sign a user up. + description: A longer description + action: send + channel: + $ref: '#/channels/userSignup' +``` + +## Field Names in Operations + +### Summary: + +This section has a short summary of what the operation is about + +``` +"summary": "Action to sign a user up.", +``` + +### Actions: + +Uses the value `send` when the application sends a message to a given channel and uses the value `receive` when the application receives a message from a given channel. + +``` +"action": "receive", +``` + +### Description + +A detailed explanation of the operation. + +``` +"description": "A longer description" +``` + +### Channel + +A `$ref` link is added to link the channels. + +``` +"channel": { + "$ref": "#/channels/userSignup" + } +``` + +### Tags + +A list of tags are used for logical grouping and categorization of operations + +``` +"tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ] +``` + +### Bindings + +A map that stores names of protocols as keys, and protocol-specific definitions as values. + +``` +"bindings": { + "amqp": { + "ack": false + } + } +``` + +### Traits + +A list of traits is added to Operations, which are merged into operations using `JSON Merge Patch`. + +``` +"traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] +``` From 595efe166575e6b8a8fb561ac350cf4a8d384e3a Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 13 Dec 2023 13:02:41 +0100 Subject: [PATCH 2/5] Update adding-operations.md --- .../asyncapi-document/adding-operations.md | 126 ++++-------------- 1 file changed, 29 insertions(+), 97 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index e5f95257f21d..1ad2c1535788 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -1,122 +1,54 @@ --- title: Adding Operations -weight: 60 +weight: 90 --- -In a messaging system, the term "operations" refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. +In a messaging system, the term `operations` refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. -In a AsyncAPI document, Operations describe the behaviors and capabilities of the messaging channels described in the AsyncAPI document. In a messaging channel, an `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. +In a AsyncAPI document, operations describe the behaviors and capabilities of the application that exchange messages through channels described in the AsyncAPI document. An `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. ## Defining Operations -Operations can be defined as an independent object in the AsyncAPI document. Operations have the following components for their definition. More information about each field name that is used to define operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationObject). -Additionally, an example to show the usage of each field name in defining operations can be found [here](https://v3.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.12#operationsObject). +Operations can be defined as an independent object in the AsyncAPI document. More information about each field name that is used to define operations can be found [in reference documentation of the specification](/docs/reference/specification/v3.0.0#operationObject). The following diagram briefs the some field names that are frequently used to define operations in a AsyncAPI document: ```mermaid -graph LR -A[Required Fields] -B[Summary] -C[Action] -D[Optional Fields] -E[Description] -F[Channel] -G[Tags] -H[Bindings] -I[Traits] -A --> B -A --> C -D --> E -D --> F -D --> G -D --> H -D --> I -style A fill:#47BCEE,stroke:#000; -style D fill:#47BCEE,stroke:#000 +flowchart LR + C[operations] + F[action] + I[channel] + A[messages] + B[reply] + D[bindings] + E[security] + C --> F + C --> I + C --> D + C --> B + C --> E + C --> A + classDef default fill:#47BCEE,stroke:#000; ``` ## Adding Operations -`operations` are separate objects in the AsyncAPI document on the root level together with `channels` and other objects. +`operations` are separate fields in the AsyncAPI document on the root level together with `channels` and other fields. Operations must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: ``` onUserSignUp: - title: User sign up - summary: Action to sign a user up. - description: A longer description - action: send + title: User sign up + summary: React and process information about new user sign up. + description: Process information about user sign up and update the information in the table that counts numbers of currently signed up users. + action: receive channel: $ref: '#/channels/userSignup' ``` -## Field Names in Operations +Above operation definition provides information that the application performs a `send` action. From the `title` and `summary` you can understand that it receives an event with information that new user just signed up to the system. -### Summary: - -This section has a short summary of what the operation is about - -``` -"summary": "Action to sign a user up.", -``` - -### Actions: - -Uses the value `send` when the application sends a message to a given channel and uses the value `receive` when the application receives a message from a given channel. - -``` -"action": "receive", -``` - -### Description - -A detailed explanation of the operation. - -``` -"description": "A longer description" -``` - -### Channel - -A `$ref` link is added to link the channels. - -``` -"channel": { - "$ref": "#/channels/userSignup" - } -``` - -### Tags - -A list of tags are used for logical grouping and categorization of operations - -``` -"tags": [ - { "name": "user" }, - { "name": "signup" }, - { "name": "register" } - ] -``` - -### Bindings - -A map that stores names of protocols as keys, and protocol-specific definitions as values. - -``` -"bindings": { - "amqp": { - "ack": false - } - } -``` - -### Traits - -A list of traits is added to Operations, which are merged into operations using `JSON Merge Patch`. - -``` -"traits": [ - { "$ref": "#/components/operationTraits/kafka" } - ] -``` +Some fields are missing from this example: +- No `messages` field means that this operation process any message comming from `userSignup` channel +- No `security` field means that there are no special security measures related to this operation and that the security that should be applied is the same as for other operations. This means that security from server level should be respected +- No `reply` field means that after reacting to user sign up, this application will not send any reply as a reaction From a2d5fb3f9eb68c0ec1d95bf0ff2f6cb98c9e823f Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Wed, 13 Dec 2023 19:44:56 +0530 Subject: [PATCH 3/5] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Alejandra Quetzalli --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 1ad2c1535788..f53b7bd97b1b 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -1,5 +1,5 @@ --- -title: Adding Operations +title: Adding operations weight: 90 --- From 32b3b408c80899a57634a8685792ca30ec2257cb Mon Sep 17 00:00:00 2001 From: Bhaswati Roy Date: Wed, 13 Dec 2023 20:14:08 +0530 Subject: [PATCH 4/5] Update pages/docs/concepts/asyncapi-document/adding-operations.md Co-authored-by: Alejandra Quetzalli --- pages/docs/concepts/asyncapi-document/adding-operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index f53b7bd97b1b..4370b1ccb040 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -3,7 +3,7 @@ title: Adding operations weight: 90 --- -In a messaging system, the term `operations` refers to the various methods by which messages are exchanged between participants or components. Operations are useful for understanding how the messaging system in AsyncAPI works, and how different components within the system communicate with each other asynchronously. They help developers and users to understand the tasks that API can perform. +In a messaging system, 'operations' are how messages are sent and received between participants or components. In AsyncAPI, understanding operations helps you see how the system sends asynchronous messages back and forth without waiting for responses. They serve as a vital tool, aiding users in comprehending the range of tasks and functionalities that the API is capable of performing. In a AsyncAPI document, operations describe the behaviors and capabilities of the application that exchange messages through channels described in the AsyncAPI document. An `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. From b0b4e7fbff697efc68c5641c3abb3d358ddc5392 Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Wed, 13 Dec 2023 07:55:24 -0800 Subject: [PATCH 5/5] tw editorial fixes --- .../asyncapi-document/adding-operations.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pages/docs/concepts/asyncapi-document/adding-operations.md b/pages/docs/concepts/asyncapi-document/adding-operations.md index 4370b1ccb040..964e8cef18fd 100644 --- a/pages/docs/concepts/asyncapi-document/adding-operations.md +++ b/pages/docs/concepts/asyncapi-document/adding-operations.md @@ -5,13 +5,13 @@ weight: 90 In a messaging system, 'operations' are how messages are sent and received between participants or components. In AsyncAPI, understanding operations helps you see how the system sends asynchronous messages back and forth without waiting for responses. They serve as a vital tool, aiding users in comprehending the range of tasks and functionalities that the API is capable of performing. -In a AsyncAPI document, operations describe the behaviors and capabilities of the application that exchange messages through channels described in the AsyncAPI document. An `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. +In an AsyncAPI document, operations describe your application's behaviors and capabilities by exchanging messages through channels configured in the AsyncAPI document. An `operation` represents a particular action or interaction that can be performed. The purpose of operations is to provide a standardized means for describing the process of sending, receiving from, requesting, or replying to messages within the messaging system. -## Defining Operations +## Defining operations -Operations can be defined as an independent object in the AsyncAPI document. More information about each field name that is used to define operations can be found [in reference documentation of the specification](/docs/reference/specification/v3.0.0#operationObject). +Operations can be defined as an independent object in the AsyncAPI document. More information about each field name that is used to define operations can be found [in the reference documentation of the specification](/docs/reference/specification/v3.0.0#operationObject). -The following diagram briefs the some field names that are frequently used to define operations in a AsyncAPI document: +The following diagram declares the field names that are frequently used to define operations in an AsyncAPI document: ```mermaid flowchart LR @@ -31,10 +31,10 @@ flowchart LR classDef default fill:#47BCEE,stroke:#000; ``` -## Adding Operations +## Adding operations -`operations` are separate fields in the AsyncAPI document on the root level together with `channels` and other fields. -Operations must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example: +In the AsyncAPI document, 'operations' are distinct fields located at the root level of the document, alongside 'channels' and other key fields. +Operations must specify on what channel they are performed by referencing the `channel` with `$ref`. For example: ``` onUserSignUp: @@ -46,9 +46,9 @@ onUserSignUp: $ref: '#/channels/userSignup' ``` -Above operation definition provides information that the application performs a `send` action. From the `title` and `summary` you can understand that it receives an event with information that new user just signed up to the system. +The operation definition mentioned above gives the details needed for the application to send a message. Its 'title' and 'summary' clearly show that it's about receiving an event when a new user signs up to the system. Some fields are missing from this example: -- No `messages` field means that this operation process any message comming from `userSignup` channel -- No `security` field means that there are no special security measures related to this operation and that the security that should be applied is the same as for other operations. This means that security from server level should be respected -- No `reply` field means that after reacting to user sign up, this application will not send any reply as a reaction +- No `messages` field means that this operation processes any message coming from the `userSignup` channel. +- No `security` field means that there are no special security measures related to this operation and that the security should be applied the same as for other operations. Essentially, the security from the server level should be respected. +- No `reply` field means that after reacting to the user sign up, this application will not send any reply as a reaction.