[📑 Docs]: Confusion regarding operation action in HelloWorld and Ping

[lerenn]

What Dev Docs changes are you proposing?

Hello there !

I'm working on a tool for golang code generation for multiple brokers, and I've been asked for the support of asyncapi v3. I'm reading through the doc to implement the new version, but something really don't cross my mind:

HelloWorld example

Here, the application is waiting for a reception as the documentation and the specification say:

Let's define an application that's capable of receiving a "hello {name}" message

operations:
  receiveHello:
    action: 'receive'
    channel:
      $ref: '#/channels/hello'

So I expect this :

graph LR
  User -- HelloWorldMessage --> Application

So okay, from what I understand:

• action: receive = Application is waiting for user message
• action: send = Application send message to user(s)

Ping example

Now with this example, I have this:

operations:
  pingRequest:
    action: send
    channel: 
      $ref: '#/channels/ping'
    reply:
      channel: 
        $ref: '#/channels/pong'

So does it means that the application is supposed to send Ping message to user(s)? And those should reply? Like this

graph LR
  Application -- Ping --> User
  User -- Pong --> Application

I suppose that's not the case because the user should be the one sending ping. So there maybe something I didn't understand.

However, if I'm right and the user send the ping, why would the operation action be send? Is it not in contradiction with the helloworld example?

Solution proposed

Adding schemas to better understand.

Sorry, I know the whole send/receive stuff was there for a better comprehension than the publish/subscribe, but for now I don't get it. Feel free to correct me ! :)

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup 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.

[smoya]

Hi @lerenn! Sorry for the delay on getting an answer.

So does it means that the application is supposed to send Ping message to user(s)? And those should reply?

Note that the example is not talking about the "user" concept here. At least in v3 of the spec, an AsyncAPI document is described from the point of view of an application. The application is not necessary a server, but can be a client as well.

In your case, that means you could have one AsyncAPI document describing the "user" application, and another one for the "server" application.

I suppose that's not the case because the user should be the one sending ping.

Not really important to the topic in discussion but just to clarify, I don't see such a limitation. For example, some systems might want to send pings to connected users.