Doubt about publish and subscribe

[javierseixas]

Hola! I'm new to asyncapi, and I have a doubt about channel specification.

In the signup example, the README says that MetricsService and EmailService are subscribe to user.signedup event. My doubt came when in the specification signup-email.yml, it says:

channels:
  /user/signedup:
    publish:
      message:
        $ref: 'signup.yml#/components/messages/userSignedUp

Notice the publish attribute. Same thing in the signup-metrics.yml

I would suppose it should be subscribe, since as the README says, the service is subscribing to the event user/signedup. It sounds more intuitive to me, at least.

Hope someone can clarify my doubts. Thanks!

[jonaslagoni]

Yea I would too. But since it has not been standardized how you view the publish/subscribe, both would actually be okay. However given this message in slack I would expect this to be a mistake. @fmvilas can you confirm this?

[fmvilas]

But since it has not been standardized how you view the publish/subscribe, both would actually be okay.

It has been standardized and has been a topic of debate. It's explained in the 3rd paragraph of the specification introduction. Although, I agree this could be explained better.

I would suppose it should be subscribe, since as the README says, the service is subscribing to the event user/signedup. It sounds more intuitive to me, at least.

To me too, especially when I'm authoring an AsyncAPI document. However, the point of view is "what your application accepts" and not what your application does. Why? Imagine you share this document with someone else and it says "subscribe". From a consumer point of view, it would make me think that I can subscribe and, therefore, the application will have to publish.

The key thing here is that AsyncAPI is defining the API, not the application behavior, and we should be able to share this document with anyone (inside the organization or not). More like OpenAPI and less like, for instance, Dockerfile, which actually describes the "workflow" in an imperative way. A similar example is when you see POST, GET, PUT, etc. in OpenAPI. It means others can POST, GET or PUT to your application not that your application is doing a POST/GET/PUT HTTP request to some server.

We'll be adding more documentation about it in the next months. It's a source of confusion, I understand. I'm sure that it will not be like that forever. Most probably, we'll have to come up with a way to avoid this confusion in version 3. Suggestions are welcome!

[javierseixas]

Thanks @fmvilas for taking the time for explaning it. I understand your point, specially taking the approach of a REST API documentation.

I don't have the whole vision of the problem, as you do, so there are parts where I may get lost. However, a difference I see with OpenAPI is that the defined communication channel is unidirectional, and accepting requests in some paths is implicit. It is not when here it is trying to define bidirectional communication with Async apps.

However, the point of view is "what your application accepts" and not what your application does.

I'm trying to read the specification following your suggestions. I read: "I can communicate with that application, using a channel named user/signedup, and this channel accepts publish messages". Here we have a verb representing an action, publish, which the application is not doing, and for me neither accepting publish. We are joining two verbs... the implicit accepts and the explicit publish. Its a bit weird. Maybe, using a noun like publications would be more undestandable.

I've seen in the signup-external.yml that for specifying a REST Api publish is also used. Also sounds a bit weird, IMO, considering a REST API doesn't publish anything either.

In summary, if you don't want to specify the application from what it does, then is probably better not to use verbs, because that's confusing. That's just my modest opinion.

[fmvilas]

We are joining two verbs... the implicit accepts and the explicit publish. Its a bit weird. Maybe, using a noun like publications would be more undestandable.

This is a great point, Javier. I'm adding it to the next meeting agenda. It would be great if you could join, you can find the calendar here so you get the event in your calendar. Also, for a bit more context consider the following:

1. AsyncAPI is not only for broker-based event-driven architectures. One example is WebSockets communication from browser to server, where there are no channels (or there's just one) and it's the same as the connection, like in HTTP APIs. Also, in this case, the pattern is client/server.
2. Where you publish might not be the same place where you have to subscribe. For instance, one might publish a message to Kafka using their HTTP connector and subscribe using the Kafka protocol in another IP address. You can always argue that the HTTP connector is another application and needs its own AsyncAPI file but that would be really bad DX.

[javierseixas]

Thanks @fmvilas for the invitation. I'll do my best for joining you (I'm at UTC-3).