docs: add operation definition for spec 3.0 #998
Conversation
buehlefs
requested review from
fmvilas,
derberg,
dalelane,
smoya,
char0n and
asyncapi-bot-eve
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.
buehlefs
changed the title
spec/asyncapi.md
Outdated
| @@ -135,11 +135,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). | |||
There was a problem hiding this comment.
| 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 the [server](#definitionsServer). Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). |
There was a problem hiding this comment.
An operation in spec 3 is something like userLogin, orderGoods, or sendPaymentInfo. All of these make sense when viewed as an operation of the message-driven API defined in an asyncapi document but not when viewed as an operation on, e.g., a kafka server that is only a part of the API implementation with the role of relaying and storing messages.
The old 2.x operations were operations like send and receive that were specifically tied to a channel/server. I am against associating the new spec 3 operation with servers, as this would make this difference harder to spot at a glance.
There was a problem hiding this comment.
Would that work for you instead?
| 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 a [channel](#definitionsChannel). Operations are performed by sending (or receiving) [messages](#definitionsMessage) to (or from) [channels](#definitionsChannel). |
I don't want to even mention the words message-driven and API because they're not defined anywhere, and their meaning is already bloated. I'm actually getting rid of the word API as much as possible because in the message-driven world, people don't perceive it as an API (that's often associated with HTTP).
Also, AsyncAPI doesn't only serve the purpose for message-driven systems. Note that we also support HTTP interactions (even more with v3). Even though, theoretically, HTTP APIs could be broken down to message exchange interactions.
There was a problem hiding this comment.
Using channel in this place is better, but still does not sit quite right with me. From my perspective the complete AsyncAPI document describes an interface for applications to use (which is pretty much the definition of API). The operations are operations of that interface while the channels are just the specific access ports where such operations can happen. That part is already covered by the second sentence.
Rather than getting rid of any mention of API in the document (this may not be feasible with the name AsyncAPI already containing API), I believe it would be better to provide a definition for it that works for this spec. We can still try to reduce usages, but this is one case where it would be beneficial to have some term for the complete interface defined by an AsyncAPI document.
There was a problem hiding this comment.
Alright. For some reason I thought we already removed all mentions of message-driven API but I can see we didn't. Good to go then 👍
|
I will probably create a new PR to resolve the merge conflicts... |
buehlefs
force-pushed
the
feature/operation-definition
branch
from
389cd84 to
4ae48a3
Compare
|
title: "Add operation definition for spec 3.0"
This PR adds the operation definition from #993 to the spec document.
The second commit adds links to the new definition in other parts of the spec.
The third rewords the description of message objects to better align with the new definition of operations in the spec and adds links to the relevant definitions.
Related issue(s): #993