Add an AsyncAPI poster showing all features at a glance

[smoya]

Reason/Context

I noticed people from serverlessworkflow.io have a poster image where they show all their features at a glance. It seems like a cheat sheet but it's more like a "here is all you can do". See https://serverlessworkflow.io/img/sw-poster.png.

I believe creating one for AsyncAPI will help potential users to quickly see and show all the things AsyncAPI can do for them, meaning adoption could be easier. Of course it can also be used as a small reference guide (even though it is not a cheat-sheet) to refresh developers knowledge.

As a user, those are few examples of questions the poster might answer to me:

• What are the things I can define in my AsyncAPI file?
• Are all the main protocols used at my company supported?
• What tooling do I have available?
• Can I generate nice documentation from my AsyncAPI file?
• Is there any IDE extension such as VSCode one?
• Can I generate code from my AsyncAPI file?

Description

• Create a visual poster. Can have several formats. Downloadables usually are pdf, but embeddable could be svg and/or png.
• Embed the poster into our website. TBD where.

[quetzalliwrites]

I love this idea and I am excited to see what others think this poster should include.

[derberg]

for me these are always like a good cheat sheet, so highlighting all features:

• bindings aka protocol agnostic
• different payload schemas support (no need for json schema, you can use avro)
• JSON $ref feature for reusability
• Traits
• example of usage with CloudEvents?
• why not example of usage with SererlessWorkflow?

and also:

• community channels where people can enage
• some cool core tools (modelina, generator, glee, others?)
• meetings calendar

Anythink I'm missing?

Might be we need 2 posters, one for AsyncAPI Specification, one for AsyncAPI tools, or event one more for AsyncAPI Initiative where we talk separately about the community 🤔

[boyney123]

Yeah think the idea is great.

Think we might also want to include the basics, or have two files maybe?

Things I would like to see (if never seen AsyncAPI):

• Operations
• Channels
• Event examples
• Application info
• etc

Maybe an intro into AsyncAPI cheatsheet too?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[smoya]

I think this is still relevant! I can't remove the stale label btw!

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[smoya]

This didn't have enough traction. Not sure if its still relevant.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[smoya]

I still think this can be useful but to be honest, after a year, not sure if this is gonna happen.

Do you still consider it something we wanna do? cc @Mayaleeeee @derberg @alequetzalli @fmvilas

[derberg]

I also think it is useful, not only a poster, kind of infographic too. We just need someone talented who could design it. And all of us can help defining what content should go there

[Mayaleeeee]

I really like the idea and would have wanted to take it on, but I'm concentrating on a mentorship program this month, so I won't have time to work on it at the moment @smoya. If it's still open by next month, though, I'll fo for it 🥰🥰😌.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[derberg]

@Mayaleeeee first someone need to specify the content, and then the poster could be worked on.

Maybe check in slack, in #specification channel, maybe someone would like to help, maybe in #docs ?

[Mayaleeeee]

Thanks @derberg I will do that

[Miracle56u]

Hi, I'd love to work on this project, I'm interested in this issue and would love to collaborate with anyone interested too

[derberg]

@Miracle56u hey, thanks What brings you here? what skills you put on the table? design or? cause this task has 2 challenges: define content + define design

[Miracle56u]

@derberg we had a meeting two days ago and this project was discussed, and I developed interest for the project to bring my design skill to the table, even though I'll yet need further clarity and understanding of the project.

[derberg]

awesome, here are some of the examples of such "posters" (more like a cheatsheets)

• https://media.cheatography.com/storage/thumb/hulj_nginx-config.750.jpg
• https://intellipaat.com/blog/wp-content/uploads/2022/10/KUBERNETES-Cheat-Sheet-2022.jpg
• https://media.cheatography.com/storage/thumb/gaston_json.750.jpg

oh looks like there is a whole service about it https://cheatography.com/

anyway, we need content, and it is not easy to provide, my only idea is that we need to hope on a call, do brainstorming and come up with something.

@smoya thoughts?

[Mayaleeeee]

Hi, I'd love to work on this project, I'm interested in this issue and would love to collaborate with anyone interested too

Thanks, Miracle. You can go ahead with it; please don't hesitate to ask if you need help.

[Miracle56u]

Thanks Mayaleeeee! Your help will surely be necessary

[Miracle56u]

Thank you @derberg for the materials.

[derberg]

so @Miracle56u how do you feel so far about the task. If you know what has to be done and more or less have an idea how to design it, we could schedule some meeting with few folks, where we brainstorm on what could be the content of such cheat sheet

[Miracle56u]

Okay @derberg That'll be great

[derberg]

Cheat Sheet Subjects:

• AsyncAPI Specification
  • Broad overview of all root element with visual representation of file
  • Features like:
    • reusability ($ref - components and traits),
    • protocol-specifics (bindings),
    • pubsub vs send/receive
    • schema format flexibility (avro and others)
    • JSON Schema and AsyncAPI Schema structuring (allOf and others) ?
    • good inspiration to look at: https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi
• Working with AsyncAPI
  • CLI
  • Studio
  • VSCode + IntelliJ
• AsyncAPI Case studies (tools)

---

So we think on online and printable version. We just need to remember that they are easy to edit, sources are in markdown or something similar.

---

Cheat sheets could have a QR code that takes you to online version of the cheat sheet - cool for people that use printed version.

[derberg]

ok then, lets do MVP with bounty support:

scope:

• drive discussion to gather content, organize meeting or anything else that will enable content production
• create a visual cheat sheet, can be png or whatever
• we do a simple cheat sheet only about spec and its features: feature name, intro and sample snippet

out of scope: putting it on website. I think we first need to see outcome of MVP, so how it looks like and later with good first issue someone can embed the picture on the website, or maybe we will need some larger discussion with documentation contributors for more complex approach. So yeah, lets not complicate to much or we will never do it 😄

I know @Mayaleeeee is very much motivated to do it, including driving discussion - so let us use the opportunity that we have website maintainer wanting to do the job

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2024-Q2, bounty/advanced, bounty/design First assignment to third-party contributors: 2024-03-22 00:00:00 UTC+12:00 End Of Life: 2024-08-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

[Mayaleeeee]

ok then, lets do MVP with bounty support:

scope:

• drive discussion to gather content, organize meeting or anything else that will enable content production
• create a visual cheat sheet, can be png or whatever
• we do a simple cheat sheet only about spec and its features: feature name, intro and sample snippet

out of scope: putting it on website. I think we first need to see outcome of MVP, so how it looks like and later with good first issue someone can embed the picture on the website, or maybe we will need some larger discussion with documentation contributors for more complex approach. So yeah, lets not complicate to much or we will never do it 😄

I know @Mayaleeeee is very much motivated to do it, including driving discussion - so let us use the opportunity that we have website maintainer wanting to do the job

Yes, I am. Thank you @derberg

[derberg]

@Mayaleeeee you are now officially assigned for the work. Super excited about this bounty issue 🚀

[aeworxet]

Bounty Issue's Timeline

Complexity Level	Assignment date (by GitHub)	Start date (by BP rules)	End date (by BP rules)	Draft PR submission	Final PR submission	Final PR merge
Advanced	2024-03-20	2024-04-01	2024-05-24	2024-04-19	2024-05-10	2024-05-24

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

[derberg]

Core

• Somehow visually show that AsyncAPI document can be used to describe any server API, including broker
• AsyncAPI is protocol agnostic - supports any protocol like MQTT, Kafka, AMQP, HTTP just to name few
• AsyncAPI can be represented as YAML or JSON

Features:

Binding

• Bindings - available in server/channel/operation/message objects
• Kafka binding example https://www.asyncapi.com/docs/tutorials/kafka/bindings-with-kafka

channels:
  userSignedUp:
    description: This channel contains a message per each user who signs up in our application.
    address: user_signedup
    messages:
      userSignedUp:
        $ref: '#/components/messages/userSignedUp'
    bindings:
      kafka:
        bindingVersion: '0.5.0'
        partitions: 10
        replicas: 2
        topicConfiguration:
          cleanup.policy: ["delete", "compact"]
          retention.ms: 604800000
          retention.bytes: 1000000000
          delete.retention.ms: 86400000
          max.message.bytes: 1048588

Multi Format Schema

Default is AsyncAPI Schema. AsyncAPI Schema is a superset of JSON Schema Draft 7 which basically means AsyncAPI Schema is the same as JSON Schema plus some additional features.

components:
  schemas:
    userSignedUp:
        type: object
        properties:
          userId:
            type: integer
            description: This property describes the id of the user
          userEmail:
            type: string
            description: This property describes the email of the user

You can use any other schema you want.

Avro example

components:
  schemas:
    userSignedUp:
      schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
      schema:
        type: record
        name: UserSignedUp
        namespace: com.company
        doc: User sign-up information
        fields:
          - name: userId
            type: int
          - name: userEmail
            type: string

Protobuf example

components:
  schemas:
    userSignedUp:
      schemaFormat: 'application/vnd.google.protobuf;version=3'
      schema: |
         message UserSignedUp {
             int32 user_id = 1;
             string user_email = 2;
         }

and make it clear that there are also other schema formats, not just protobuf or avro, that can be used

Extensions

way to extend standard AsyncAPI spec with additional fields

asyncapi: 3.0.0
info:
  title: Cool Example
  version: 0.1.0
  x-linkedin: '/company/asyncapi' 

Reusability

Reusability inside single AsyncAPI document

components:
  messages:
    UserSignedUp:
      payload:
        $ref: '#/components/schemas/UserSignedUp'
  schemas:
    UserSignedUp:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

Reusability outside document, pointing to a file

components:
  messages:
    UserSignedUp:
      payload:
        $ref: '#/components/schemas/UserSignedUp'
  schemas:
    UserSignedUp:
        $ref: './userSchema.json'

Reusability outside document, pointing to URL

components:
  messages:
    UserSignedUp:
      payload:
        $ref: '#/components/schemas/UserSignedUp'
  schemas:
    UserSignedUp:
        $ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp

Traits

tbc