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: added content for operations in AsyncAPI Document #2171

Closed
wants to merge 27 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
7c6b514
document adding-operations
BhaswatiRoy Sep 26, 2023
4fff5f3
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
d361b7f
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
46f9487
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
c59b9fd
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
26e0044
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
e5d0e60
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
7a9903f
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
2ea6b05
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
f23afda
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
ea07641
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 3, 2023
551940c
updated the adding operations sub section
BhaswatiRoy Oct 30, 2023
9749db3
updated adding operations subsection
BhaswatiRoy Oct 30, 2023
b3643a8
removed unwanted characters
BhaswatiRoy Oct 30, 2023
5b4767e
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 30, 2023
8ab1445
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 30, 2023
dc93f5a
updated the changes including diagrams, and addition of content
BhaswatiRoy Oct 30, 2023
c8ef443
Merge branch 'gsod-work-1' of https://github.com/BhaswatiRoy/website …
BhaswatiRoy Oct 30, 2023
9e7a602
updated changes
BhaswatiRoy Oct 30, 2023
aaf499f
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 31, 2023
61679a6
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Oct 31, 2023
c0da456
removed duplicate lines
BhaswatiRoy Oct 31, 2023
debd164
aligned mermaid diagram code with other writers
BhaswatiRoy Oct 31, 2023
8f5f1da
updated mermaid diagram to align with the style guide
BhaswatiRoy Nov 1, 2023
af6fa6c
added field name details in operations
BhaswatiRoy Nov 1, 2023
511e89a
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Nov 7, 2023
436b618
Update pages/docs/concepts/asyncapi-document/adding-operations.md
BhaswatiRoy Nov 7, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions pages/docs/concepts/asyncapi-document/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'AsyncAPI Document'
weight: 50
---
127 changes: 127 additions & 0 deletions pages/docs/concepts/asyncapi-document/adding-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
---
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:
BhaswatiRoy marked this conversation as resolved.
Show resolved Hide resolved
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" }
]
```