Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: adding content about adding operations #2403

Merged
merged 7 commits into from
Dec 13, 2023
Merged
54 changes: 54 additions & 0 deletions pages/docs/concepts/asyncapi-document/adding-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
---
title: Adding Operations
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved
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.
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved

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.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

## Defining Operations
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

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).
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

The following diagram briefs the some field names that are frequently used to define operations in a AsyncAPI document:
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

```mermaid
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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

`operations` are separate fields in the AsyncAPI document on the root level together with `channels` and other fields.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
Operations must specify on what channel it is performed. You do it by referencing the `channel` with `$ref`, just like in the following example:
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

```
onUserSignUp:
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'
```

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.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

Some fields are missing from this example:
- No `messages` field means that this operation process any message comming from `userSignup` channel
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- 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
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
- No `reply` field means that after reacting to user sign up, this application will not send any reply as a reaction
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved