Calling for Votes : Document popular protocol processes/tasks to accomplish with AsyncAPI

[VaishnaviNandakumar]

Hello!

As a part of the AsyncAPI Mentorship Program 2023, we’re creating new documentation for configuring different protocols with AsyncAPI. Vote on which protocols to prioritize documenting for this year’s program scope. List popular processes/topics/tasks you accomplish with AsyncAPI and your protocols of choice.

At the end of this vote, we will create documentation covering selected protocols from the other GSoD community vote for selecting protocols to prioritize in the 2023 Mentorship project scope.

🚀 Example topics to pitch:

• Validate AsyncAPI document using MQTT
• Create an AsyncAPI document using WebSocket
• Validate messages using Kafka

✨ Our documentation is currently organized into the following content buckets:

• Concepts : Defines the fundamental features and capabilities of AsyncAPI, providing a solid understanding of its principles.
• Tutorials : Offers step-by-step walkthroughs for individuals new to AsyncAPI, ensuring a smooth onboarding experience.
• Guides : Provides a high-level overview of AsyncAPI's capabilities, helping users navigate its functionalities effectively.
• Tools : Documents AsyncAPI's tools ecosystem, showcasing the diverse range of tools available to enhance your experience.
• Reference : Offers documentation on the AsyncAPI specification.
• Community : Presents documentation on community guidelines and resources.

This discussion will be closed after two weeks.
Vote and comment below on the resources you’d like to see covered.

📢NOTE: The community vote for selecting protocols to document in our 2023 Mentorship Program is being conducted over here

Cc: @deberg @alequetzalli @fran @asyncapi/tsc_members

[mtitinger]

(copied over from https://github.com/orgs/asyncapi/discussions/379#discussioncomment-6574374, thank!)

Hello all,

IDK if this topic is considered closed, but here is some input.

I am considering using AsyncAPI as a formalism to do Model-based design. This idea is that adding properties to our device ecosystem is first done by describing the properties in the form of a schema.yaml, and ideally using generator for the different bindings (mqtt/c++) and documentation we need.

I have a prototype model repo, validated with AsyncStudio, and c++ generation produces code I can imagine to use in an embedded context, so far so good. One source of hesitation for me at this point is the complexity of aggregating several schema files. Ideally I do not wish to ask my contributors to add new channels, components, messages, traits etc... is the same file.

There are few example here and there on using refs, or python tooling to aggregate or split schema part, but it seems a bit fiddly to me at least, so I'm not sure this is the right way to go.

Some tutorial and example material for "distributed" model files would be great.

It seems quite natural to have for each functional blocs of technical domain in the system, a dedicated schema file, with channels, message, payload layouts, etc... that the framework is able to aggregate to one schema file that can be used for generation.

Thanks and regards,
Marc.

[VaishnaviNandakumar]

Hi @mtitinger. That's a great suggestion! However, we are looking for more protocol-specific tasks right now. We could add handling multiple schema refs as a part of a tutorial for a specific protocol. What do you think about that?

[mtitinger]

Hello @VaishnaviNandakumar

that sounds great, I'm sure the multiple-ref scheme can then be easly infered for any protocol. And, if by protocol you mean for instance mqtt, it would be just perfect !

Many thanks,
M.

[derberg]

@mtitinger hey, hopping in early to already identify what content would have to be provided. Can you please clarify, if what I understand is correct.

You'd like to have a guide that basically explains on how to structure AsyncAPI documents, how to use them at scale (with multiple contributors), maybe even examples on how others do it in production, even a section about how people manage schemas with schemas registries?

In short, you need a guide that is much more detailed version (with examples) of https://www.asyncapi.com/blog/organizing-asyncapi-documents?

[mtitinger]

Hi @derberg sorry for the late reply, maybe let me somewhat rephrase what I was finding difficult to get doc for, I hope it’s not TLDR.

Suppose I have a device with different sub-systems, like say “audio” and “radio”.
I want to expose one common interface through mqtt, to exploit those sub-systems, with topics like
device/{id}/radio/# (many channels)
device/{id}/audio/# (many channels)

In my team we will have to make changes or additions to the device properties in a model-based approach : the first step will be to write or modify the matching yaml for a given channel.
For clarity and maintainability, I would like to have separate schema files for each subsystem:
radio-schema.yaml
audio-schema.yaml
Of course, they might share model files for traits, messages, or various components using refs, as covered by your link.
Now, what is not clear, is how I can feed those multiples schema file to a generator, but still have one common generated binding library instead of generating for each schema file an independent APIs, each having its mosquito init stub.

One way to do this is to write python tools for instance, to basically merge all schema files into one. But I’m finding this is somewhat unsatisfying, I’d expect us to be able to have multiple components or channel sections referenced from different files. I was not able to achieve this so far using refs, but maybe it’s me not having the right doc.

Many thanks,
Marc.

[CynthiaPeter]

In a discussion about preferred protocols here, the following protocols were voted most, and going by that, I will suggest topics suitable for these protocols and what categories they could fall under:

Most voted protocols:

• AMQP
• WebSockets
• Kafka

Topics	Description
Publish-Subscribe Messaging with AMQP	Document how to set up publish-subscribe patterns using exchanges and queues.
Security and Authentication (AMQP)	Specify authentication and authorization mechanisms for AMQP connections.
Cluster Configuration (AMQP)	Explain how to set up and configure AMQP clusters for fault tolerance and high availability.
Message Routing and Filtering (AMQP)	Explain how to route and filter messages based on criteria.
Message Payload Structure (Websockets)	Define the structure of WebSocket messages, including data and metadata.
Event Subscription and Broadcasting (Websockets)	Document how clients can subscribe to events and how servers can broadcast messages.
Scaling and Load Balancing (Websockets)	Discuss strategies for scaling WebSocket applications and load balancing.
Topic Configuration (Kafka)	Document how to create and configure Kafka topics for message publishing.
Retention Policies (Kafka)	Document how to configure retention policies for managing message retention duration
Consumer Group Setup (Kafka)	Explain how to set up consumer groups for parallel processing of messages