docs: add operation definition for spec 3.0 #1006
Conversation
buehlefs
requested review from
fmvilas,
derberg,
dalelane,
smoya,
char0n and
asyncapi-bot-eve
as code owners
|
spec/asyncapi.md
Outdated
| @@ -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). | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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):
| 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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
|
/ptal |
|
@char0n @fmvilas @GreenRover @dalelane @derberg Please take a look at this PR. Thanks! 👋 |
|
This pull request has been automatically marked as stale because it has not had recent activity 😴 It will be closed in 120 days if no further activity occurs. To unstale this pull request, add a comment with detailed explanation. There can be many reasons why some specific pull request has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model. Let us figure out together how to push this pull request forward. Connect with us through one of many communication channels we established here. Thank you for your patience ❤️ |
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
Previous PR: #998 (opened new PR because of merge conflicts after spec 3 release)