Closed smoya closed 3 months ago
I love this idea and I am excited to see what others think this poster should include.
for me these are always like a good cheat sheet, so highlighting all features:
and also:
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 🤔
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):
Maybe an intro into AsyncAPI cheatsheet too?
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:
I think this is still relevant! I can't remove the stale
label btw!
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:
This didn't have enough traction. Not sure if its still relevant.
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:
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
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
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 🥰🥰😌.
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:
@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 ?
Thanks @derberg I will do that
Hi, I'd love to work on this project, I'm interested in this issue and would love to collaborate with anyone interested too
@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
@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.
awesome, here are some of the examples of such "posters" (more like a cheatsheets)
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?
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.
Thanks Mayaleeeee! Your help will surely be necessary
Thank you @derberg for the materials.
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
Okay @derberg That'll be great
Cheat Sheet Subjects:
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.
ok then, lets do MVP with bounty support:
scope:
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
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
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
@Mayaleeeee you are now officially assigned for the work. Super excited about this bounty issue 🚀
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 |
Core
Features:
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
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
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'
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
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: './userSchema.json'
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp
tbc
recording of meeting: https://www.youtube.com/watch?v=6lVMY_Fc0Vs
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 ofJSON Schema Draft 7
which basically meansAsyncAPI Schema
is the same asJSON 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
Thanks a lot! @derberg
Your explanation was great.
Hello everyone!
During the first and second weeks, I focused on learning about cheat sheet design, including the best approaches for creating a user-friendly cheat sheet poster.
In the first week, I had a livestream meeting with Lukasz where we discussed the cheat sheet and how to approach it. You can find the link to the meeting here.
Here are some of the examples Lukasz mention and I have been exploring.
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
For next week: 15/04/2024 - 19/04/2024
I'd like to take the week off for my final exams and would return next week to start working on the design.
cc @aeworxet
Thank you, and have a great day!
Upon request of the Bounty Program Participant (@Mayaleeeee), the Bounty Issue's Timeline is extended.
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-31 | 2024-04-26 | 2024-05-17 | 2024-05-31 |
After analyzing the discussion on the content for the AsyncAPI Cheat Sheet, I designed a layout that best captures all of our ideas and suggestions.
You can easily access the design below 👇🏾 or via this Figma link.
cc @derberg
Hey, nice first version! Could it be that binding examples are on one side and schemas on the other? and extensions and reusability in middle? as now it is a bit chaotic.
there are some errors in yaml examples, but these are like "grammar" issues we can deal at the end. Take into account that we could print it as brochure, 2 sided, so bindings and multi schema examples, can be all on the other side, and on first side he can put basics
Hey, nice first version! Could it be that binding examples are on one side and schemas on the other? and extensions and reusability in middle? as now it is a bit chaotic.
there are some errors in yaml examples, but these are like "grammar" issues we can deal at the end. Take into account that we could print it as brochure, 2 sided, so bindings and multi schema examples, can be all on the other side, and on first side he can put basics
Alright. I'll do that and come up with something.
Thanks for the feedback.
Hi @derberg these are the YAML snippets you requested.
Binding - Channels
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
Binding - Operations
operations:
onUserSignedUp:
action: receive
channel:
$ref: '#/channels/userSignedUp'
bindings:
kafka:
bindingVersion: '0.5.0'
groupId:
type: string
enum: ['myGroupId']
clientId:
type: string
enum: ['myClientId']
Binding - Message
components:
messages:
userSignedUp:
bindings:
kafka:
key:
type: string
enum: ['myKey']
schemaIdLocation: 'payload'
schemaIdPayloadEncoding: 'apicurio-new'
schemaLookupStrategy: 'TopicIdStrategy'
bindingVersion: '0.5.0'
payload:
schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0'
schema:
$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp
Binding - Server
servers:
kafkaServer:
host: test.mykafkacluster.org:8092
description: Kafka Server
protocol: kafka
bindings:
kafka:
schemaRegistryUrl: 'http://localhost:8080/apis/registry/'
schemaRegistryVendor: 'apicurio'
bindingVersion: '0.5.0'
Default - AsyncAPI Schema
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
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
components:
schemas:
userSignedUp:
schemaFormat: 'application/vnd.google.protobuf;version=3'
schema: |
message UserSignedUp {
int32 user_id = 1;
string user_email = 2;
}
Single 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
URL
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp
To a file
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: './userSchema.json'
asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
x-linkedin: '/company/asyncapi'
Ok, so we should have a poster on two A4 pages, so we can print it on one card
page 1 - should be basic explanation and core features page 2 - extra features, basically bindings and schemas
so, Page 1
Fixed content:
- It is an open source specification that makes it easier to work with even-driven architectures by helping with design, documentation and managing of asynchronous APIs,
- It is protocol agnostic and you can use it with protocols like MQTT, Kafka, AMQP, WebSocket, just to name few
- It can be represented with machine-readable formats like YAML and JSON
Please try instead of one box with above text, have them all shared in a context of a picture:
I think we can get rid of the box and provide texts in context, where example YAML samples are
- Bindings - additional protocol-specific information you can add to AsyncAPI document
- Multi Format Schema - by default you can use AsyncAPI Schema that is a superset of JSON Schema Draft 7. Multi format allows you to use other formats, like OpenAPI Schema, Apache Avro, Protobuf and others.
- Extensions - with x- prefix you can add additional fields to AsyncAPI documents to fulfil your specific use cases
- Reusability - you can reuse all parts of AsyncAPI, within one document or by pointing to external resources, separate files or servers that for example can host schemas.
because of the amount of snippets for bindings + multiformat + reusability make sure they end up in Page 2 with above descriptions.
in case of MultiFormat - the visual with JSON and AsyncAPI Schema is not helping much so we can remove it imho
so on Page 1 I guess only extensions would stay 🤔
and if because of all above, we get a bit more space to occupy on Page 1, we could maybe place QR codes that would point to Studio and CLI to promote them as core tools to work with AsyncAPI?
Binding - Channels
channels:
userSignedUp:
address: user_signedup
messages:
userSignedUp:
$ref: '#/components/messages/userSignedUp'
bindings:
kafka:
bindingVersion: '0.5.0'
partitions: 10
replicas: 2
topicConfiguration:
cleanup.policy: ["delete", "compact"]
Binding - Operations
operations:
userSignup:
action: receive
channel:
$ref: '#/channels/userSignedUp'
bindings:
mqtt:
qos: 2
retain: true
bindingVersion: 0.2.0
Binding - Message
components:
messages:
userSignedUp:
payload:
$ref: '#/components/schemas/userSignedUp'
bindings:
amqp:
contentEncoding: gzip
messageType: 'user.signup'
bindingVersion: 0.3.0
Binding - Server
servers:
production:
bindings:
pulsar:
tenant: contoso
bindingVersion: '0.1.0'
Default - AsyncAPI Schema
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
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
components:
schemas:
userSignedUp:
schemaFormat: 'application/vnd.google.protobuf;version=3'
schema: |
message UserSignedUp {
required int32 user_id = 1;
optional string user_email = 2;
}
Single 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
URL
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: http://localhost:8080/apis/registry/v2/groups/my-group/artifacts/UserSignedUp
To a file
components:
messages:
UserSignedUp:
payload:
$ref: '#/components/schemas/UserSignedUp'
schemas:
UserSignedUp:
$ref: './userSchema.json'
asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
x-linkedin: 'https://www.linkedin.com/company/asyncapi'
- It can be represented with machine-readable formats like YAML and JSON
Based on the explanation above, this is the design I was able to come up with. @derberg
Hello, everyone; here's an update on the cheat sheet design I've been working on. Throughout last week, I updated the design according to Lukasz's suggestions, and here's where we are currently at. cc @derberg @aeworxet
I marked with red parts that are missing indent, or indent is barely visible with bare eye
also marked one place where wrong part is bold
Last week, I made further updates to the cheat sheet based on Lukasz's suggestions. Here is the final design in different formats. cc @derberg @aeworxet
SVG Format
PNG
can't wait to get it print out and share with people at APIDays Helsinki
work completed
also 200 copies for APIDays Helsinki printed.
some followup work will be done in https://github.com/asyncapi/website/issues/2982
and any improvements to current design, I'll create issues whenever there is some feedback from any event
@smoya thanks for suggesting this topic
@Mayaleeeee huge thanks for great execution
@Mayaleeeee, please go to the AsyncAPI page on Open Collective and submit an invoice for USD 400.00
with the expense title Bounty website#425
, tag bounty
, and full URL of this Bounty Issue in the description.
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:
Description