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.

Sign up for GitHub

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: add operation definition for spec 3.0 #1006

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
Open

docs: add operation definition for spec 3.0 #1006

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4e0a02d
docs: add definition for operation (#993)
buehlefs Nov 30, 2023
4b0ef29
docs: add links to operation definition
buehlefs Nov 30, 2023
9bf317d
docs: reword message object description to align with new operation d…
buehlefs Nov 30, 2023
c36274f
docs: add toc entry for operation definition
buehlefs Apr 10, 2024
6caa3e8
docs: reword operation definition
buehlefs Apr 10, 2024
8945fce
Merge branch 'master' into feature/operation-definition
buehlefs Apr 22, 2024
ecb3a89
Fix missing newline
buehlefs Apr 24, 2024
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
23 changes: 13 additions & 10 deletions spec/asyncapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The AsyncAPI Specification is a project used to describe message-driven APIs in
The AsyncAPI Specification defines a set of files required to describe the API of an [application](#definitionsApplication).
These files can be used to create utilities, such as documentation, code, integration, or testing tools.

The file(s) SHOULD describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet:
The file(s) SHOULD describe the [operations](#definitionsOperation) an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet:

```yaml
channels:
Expand All @@ -34,7 +34,7 @@ It means that the [application](#definitionsApplication) will receive messages f

**The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol.

It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following receiver snippet:
It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the [operation](#definitionsOperation) might stop making sense. For instance, given the following receiver snippet:

```yaml
operations:
Expand Down Expand Up @@ -131,11 +131,14 @@ A sender is a type of application, that is sending [messages](#definitionsMessag
### <a name="definitionsReceiver"></a>Receiver
A receiver is a type of application that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY receive from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY forward a received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and forwards them.

### <a name="definitionsOperation"></a>Operation
An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this as the opposite. An Operation is an action the API/Application performs. For example, if the action is send, It means the application API defined in the current AsyncAPI document is sending a message.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would never say, that an API performs some operation, as the API is just the description of the interface that is implemented by some application. I am on the same side with the direction of send and receive. I could add something like "Operations are always described from the point of view of the application." to make it clearer in which direction send and receive take their effect. (I was hoping that the context of the first sentence would make this clear already.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, you are right about the API term. However, I'm confused about the meaning of this sentence then:

a specific action an application can take to interact with the message-driven API

So you mean the application which defines the Application API through the AsyncAPI Document takes actions to interact, but with who?
I think the issue is more on the with the message-driven API part. Maybe with the users of it's API or similar will make it more clear?
I leave this for you so you can come up with a better alternative than me (for sure).

Copy link
Author

@buehlefs buehlefs Mar 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, this is the tricky part. An AsyncAPI spec can describe operations for "consumers" of an API or for "providers" of an API. Especially with async APIs it is not always clear if an application is a pure consumer or provider of the API. The spec intentionally allows to document both kinds of applications.

This has language for both applications but is potentially more confusing:

a specific action an application can take to interact with or implement part of the message-driven API.

Or we state explicitly with whom the application interacts:

a specific action an application can take to interact with other sender or receiver applications [through the message-driven API].

I understand that the message-driven API term is confusing as it does not have a clear definition. I think that we should have a definition for that term (at least in the context of an AsyncAPI file), but that is a separate issue.
The AsyncAPI document clearly defines some kind of API. I would suggest calling the sum of all operations a view of (or a part of) the message-driven API (or interface) of the application.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An AsyncAPI spec can describe operations for "consumers" of an API or for "providers" of an API. Especially with async APIs it is not always clear if an application is a pure consumer or provider of the API. The spec intentionally allows to document both kinds of applications.

Since v3, this statement was added:

The AsyncAPI document SHOULD describe the operations an application performs.

Source: https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md?plain=1#L19

Wouldn't we just document from that point of view as the standard? Honest question.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. I just wanted to point out that the application can have an operation sendLoginCredentials (I would call this application a consumer/client of an API) while another application will have receiveLoginCredentials as operation (providing the API). Both applications can be described in an AsyncAPI document.

The AsyncAPI document SHOULD describe the operations an application performs.

Wouldn't we just document from that point of view as the standard? Honest question.

If this is one of the core principles behind AsyncAPI, then we should make this more prominent. Currently, I feel that it is often unclear if an AsyncAPI document describes an API, an Application, a set of Channels/Operations, or even a system of multiple Applications. While this sentence addresses this confusion, it is not enough. Repeating this information in a definition for "AsyncAPI [document]" would help improve its visibility.

As for this PR: I am currently leaning towards the second option, as it concretely describes what an operation is used for without referencing an API.
I will make this change later today (and also update the toc):

Suggested change
An operation describes a specific action an [application](#definitionsApplication) can take to interact with the message-driven API. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).
An operation describes a specific action an [application](#definitionsApplication) can take to interact with other [sender](#definitionsSender) or [receiver](#definitionsReceiver) applications. Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this sentence addresses this confusion, it is not enough. Repeating this information in a definition for "AsyncAPI [document]" would help improve its visibility.

I can agree this is not be super cristal clear. I invite you to open a new issue so we can work on it; happy to push it forward.

The point is that it is a fact, one single AsyncAPI document should describe no more than one application. An exception to this, would be an AsyncAPI document with all definitions located under components. That would be considered as a "menu" of components, such as channels, servers, operations, which can be reused by those individual AsyncAPI documents. At the end, that file could be describing your broker.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will probably open an issue for this once this PR is merged. I have updated this PR to my suggested change above.

There is one more case: Multiple AsyncAPI documents may be used to describe different APIs of the same application (e.g., public facing API vs. internal API). So it is not 1 to 1 for AsyncAPI document to application.

Copy link
Member

@smoya smoya Apr 18, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So it is not 1 to 1 for AsyncAPI document to application.

There is no limitation on the number of documents. We talk about 1:1 because it's the most common scenario. But it all depends on how you want to expose those AsyncAPI documents to the users.
AsyncAPI spec doesn't limit anything on that side.


### <a name="definitionsMessage"></a>Message
A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MAY contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response.

### <a name="definitionsChannel"></a>Channel
A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers.
A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive messages from channels to perform an [operation](#definitionsOperation). [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers.

### <a name="definitionsProtocol"></a>Protocol
A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar.
Expand Down Expand Up @@ -201,7 +204,7 @@ Field Name | Type | Description
<a name="A2SServers"></a>servers | [Servers Object](#serversObject) | Provides connection details of servers.
<a name="A2SDefaultContentType"></a>defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload.
<a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication).
<a name="A2SOperations"></a>operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement.
<a name="A2SOperations"></a>operations | [Operations Object](#operationsObject) | The [operations](#definitionsOperation) this [application](#definitionsApplication) MUST implement.
<a name="A2SComponents"></a>components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication).

This object MAY be extended with [Specification Extensions](#specificationExtensions).
Expand Down Expand Up @@ -466,7 +469,7 @@ Field Name | Type | Description
<a name="serverObjectTitle"></a>title | `string` | A human-friendly title for the server.
<a name="serverObjectSummary"></a>summary | `string` | A short summary of the server.
<a name="serverObjectVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)]] | A map between a variable name and its value. The value is used for substitution in the server's `host` and `pathname` template.
<a name="serverObjectSecurity"></a>security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or operation.
<a name="serverObjectSecurity"></a>security | [[Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | A declaration of which security schemes can be used with this server. The list of values includes alternative [security scheme objects](#securitySchemeObject) that can be used. Only one of the security scheme objects need to be satisfied to authorize a connection or [operation](#definitionsOperation).
<a name="serverObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping and categorization of servers.
<a name="serverObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) \| [Reference Object](#referenceObject) | Additional external documentation for this server.
<a name="serverObjectBindings"></a>bindings | [Server Bindings Object](#serverBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.
Expand Down Expand Up @@ -766,7 +769,7 @@ Holds a dictionary with all the [operations](#operationObject) this application

Field Pattern | Type | Description
---|:---:|---
<a name="operationsObjectOperation"></a>{operationId} | [Operation Object](#operationObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
<a name="operationsObjectOperation"></a>{operationId} | [Operation Object](#operationObject) \| [Reference Object](#referenceObject) | The [operation](#definitionsOperation) this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

##### Operations Object Example

Expand Down Expand Up @@ -819,7 +822,7 @@ onUserSignUp:

#### <a name="operationObject"></a>Operation Object

Describes a specific operation.
Describes a specific [operation](#definitionsOperation).

##### Fixed Fields

Expand Down Expand Up @@ -966,7 +969,7 @@ bindings:

#### <a name="operationReplyObject"></a>Operation Reply Object

Describes the reply part that MAY be applied to an Operation Object. If an operation implements the request/reply pattern, the reply object represents the response message.
Describes the reply part that MAY be applied to an Operation Object. If an [operation](#definitionsOperation) implements the request/reply pattern, the reply object represents the response message.

##### Fixed Fields

Expand All @@ -980,7 +983,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens

#### <a name="operationReplyAddressObject"></a>Operation Reply Address Object

An object that specifies where an operation has to send the reply.
An object that specifies where an [operation](#definitionsOperation) has to send the reply.

For specifying and computing the location of a reply address, a [runtime expression](#runtimeExpression) is used.

Expand Down Expand Up @@ -1221,7 +1224,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens

#### <a name="messageObject"></a>Message Object

Describes a message received on a given channel and operation.
Describes a [message](#definitionsMessage) that can be sent to or received from a given [channel](#definitionsChannel) to perform an [operation](#definitionsOperation).

##### Fixed Fields

Expand Down