Update tutorials/documentation to reflect publish/subscribe semantics

[karloskalcium]

There are several areas in the tutorials/documentation where publish/subscribe semantics are in need of correction or could be updated to be more clear:

1. The Hello World https://asyncapi.io/docs/getting-started/hello-world/

   I would argue that the Hello World example, if we're starting with that, should initially be an example of an event publisher vs an event consumer. The most common 'hello-world' application prints out "Hello World" to the screen, so the first example should do the same IMO - e.g. publish a 'hello world' message to a queue.

2. This line is a bit unclear:
   You can read the highlighted lines as “this is the payload of the message your app can publish to the «hello» channel”.

   When we say "your app", at this point we are not describing the 'hello-world' app, but rather a separate publisher app. that makes this example a bit confusing. I would suggest that reworking the example to focus on a publisher vs consumer would make this more clear.

3. On this page, the code switches semantics to using a 'subscribe' vs 'publish' option - we should make this the same as the first part of the tutorial

4. On this page, it defines a publisher that uses 'publish' actions - again we should make these all the same. IMO, that should be the examples are always about publishers, and they always use 'subscribe' actions.

5. In the streetlights tutorial, it says the following:
   We’ll publish messages to the broker and that’s it. Our service don’t know who will receive them.
   However, this is a bit strange, because later on the page you are creating the service that will receive these events - and you aren't actually ever creating the services that send the events. This confused me for a while...

   Also the API is defined as follows:The Smartylighting Streetlights API allows you to remotely manage the city lights.

   However, as defined, this api is not really able to 'manage' the lights, it's only able to monitor them.

6. I found this blog post really useful:
   However, it uses the old semantics - defining a userService that publishes (and uses the publish action). Now that 2.0 is out, and a decision has made to switch semantics, the old blog post should be IMO reworded with the right examples.

7. We could even extend the hello-world example to have both a publisher and a consumer, sharing a common message definition. This way we can explain the idea of reuse of message contents in the tutorial itself.

8. Finally the spec itself should have a clearly elaborated section describing the different between publish and subscribe in formal terms. Currently it just has A definition of the SUBSCRIBE operation.. This should be enhanced with clear description of when an API should define a SUBSCRIBE operation (namely, to tell "clients" of the API that they can subscribe to that channel in order to get messages sent by this publisher)

I made an initial PR, but I realize that some parts of it are incorrect now. So let's discuss here in this issue what needs to be done, then I will update the PR accordingly.

[fmvilas]

Thanks for the thoughtful description, Karl. I lack time myself to discuss this but a folk will join us soon and he will be in charge of these things. Looking forward!

[derberg]

Hi @karlwbrown. Thanks for such a detailed input:

1. What is the difference here really? In eventing, it is always about sending and consuming. This simple tutorial talks about consuming. What difference it would make if we switch to publishing, we would just have to rephrase a bit and change the channel operation to subscribe. Maybe we simply need another tutorial where subscribe operation is addressed?
2. I had exactly the same confusion in my head because of this your app statement :) it is now rephrased in docs to:

This is the `payload`` of the `message` that `Hello world application` is subscribed to. You can `publish` the `message` to `hello` channel and `Hello world application` app will receive it

3. Totally agree, I did not notice it when I was doing some updates Good eye
4. Can you explain more, I did not get it. I see that in this case operation is in sync with previous Hello world doc, not like in case of doc about servers
5. It might be a bit confusing at the beginning I guess. Wouldn't some good arch diagram of the example explain it? with an " event triggering" service (some controller seating next to the bulb), a broker in the middle and then Streetlights API that consumes the information about the light and can react.
6. I think the best would be simply to write a new one, and in the old one make a note that it is about 1.0. Blog post is a great idea.
7. You suggest the same channel, hello?
8. How would you extend the current description exactly?

Thank a lot again

[karloskalcium]

Hi @karlwbrown. Thanks for such a detailed input:

1. What is the difference here really? In eventing, it is always about sending and consuming. This simple tutorial talks about consuming. What difference it would make if we switch to publishing, we would just have to rephrase a bit and change the channel operation to subscribe. Maybe we simply need another tutorial where subscribe operation is addressed?

I see your point. However, in my (admittedly brief) experience it is slightly more common that the message producer defines the interface for the message that will be emitted, and consumers will then comply with that. Obviously there are the opposite cases, but I would hazard that many use cases of eventing involve few producers with (possibly) many consumers, and the producer spec may be more utilized vs the consumer specs may be less so.

We could also have what you suggest, which is a clear and more specific use case for publish vs subscribe use case, and document it as such.

Or, going off one of the suggestions lower down, what if we update the tutorial to have both - a consumer spec and a producer spec, sharing the same message. This would make it even clearer, and could give an example of how to share a message definition as well potentially.

2. I had exactly the same confusion in my head because of this your app statement :) it is now rephrased in docs to:

This is the `payload`` of the `message` that `Hello world application` is subscribed to. You can `publish` the `message` to `hello` channel and `Hello world application` app will receive it

Yup, that sounds better now.

1. Totally agree, I did not notice it when I was doing some updates Good eye
2. Can you explain more, I did not get it. I see that in this case operation is in sync with previous Hello world doc, not like in case of doc about servers

in this one:
https://asyncapi.io/docs/getting-started/security/

the urn says 'hello-world-publisher', but the action is 'publish' which, somewhat confusingly, is what a consumer would put in their spec.

3. It might be a bit confusing at the beginning I guess. Wouldn't some good arch diagram of the example explain it? with an " event triggering" service (some controller seating next to the bulb), a broker in the middle and then Streetlights API that consumes the information about the light and can react.

yup, an architecture diagram would help a lot here...

4. I think the best would be simply to write a new one, and in the old one make a note that it is about 1.0. Blog post is a great idea.

Sure, agreed. Keep the old 1.0, make a new blog post, with new semantics, explaining basically the same thing but noting that it is for 2.0.

5. You suggest the same channel, hello?

Sure - maybe the hello world example has both publisher and consumer. So instead of choosing one or the other, we give them the full example - here is how the publisher would spec out the messages they are sending, here is how the consumer would specify messages they are receiving.

6. How would you extend the current description exactly?

I'd have to look at the spec again. I'd just (generally) have a paragraph and maybe a table explaining this. e.g.

Action	Who uses this action	What this means
publish	Subscribers / consumers / clients	The application in question will listen to this channel for this message. In order to reach me, you need to publish to that channel
subscribe	Publishers / producers /servers	The application in question will emit messages to this channel. In order to capture those events, you need to subscribe to that channel

It remains a bit confusing that publishers put the subscribe action in the spec and subscribers put the publish action in the spec. I understand the reasoning, I just think more crystal clear explanation of it would make it easier to grok.

Thank a lot again

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️