Update tutorials/documentation to reflect publish/subscribe semantics #40
Comments
|
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! |
|
Hi @karlwbrown. Thanks for such a detailed input:
Thank a lot again |
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.
Yup, that sounds better now.
in this one: the urn says 'hello-world-publisher', but the action is 'publish' which, somewhat confusingly, is what a consumer would put in their spec.
yup, an architecture diagram would help a lot here...
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.
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.
I'd have to look at the spec again. I'd just (generally) have a paragraph and maybe a table explaining this. e.g.
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.
|
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
This issue has been automatically marked as stale because it has not had recent activity 😴 |
|
We recently updated spec with the proper info and now will have a blog post about it too. so closing as progress on blog post will be tracked separately |
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:
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.
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.
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
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.
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.
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.
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.
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.
The text was updated successfully, but these errors were encountered: