-
-
Notifications
You must be signed in to change notification settings - Fork 694
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: created a Glossary list #1784
Changes from 2 commits
925cf2a
5a8d571
fd6000b
be5c076
ff1ae3b
663dcbb
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
--- | ||
title: Glossary | ||
weight: 10 | ||
--- | ||
|
||
|
||
This Glossary serves as a central location for terms that appears in the AsyncAPI documentation. If you find a term that you wish was defined here, please post an [issue requesting it](https://github.com/asyncapi/website/issues). | ||
|
||
|
||
## API | ||
The general definition of "Application Program Interface" can refer to different things for different people. However, in this case, APIs refer to different kinds of APIs, including HTTP-based, Async, and Event-driven Architecture. | ||
|
||
|
||
## AsyncAPI | ||
AsyncAPI is an open specification that allows you to describe and document asynchronous APIs (Application Programming Interfaces). It focuses on the communication patterns and message-driven architectures commonly found in event-driven systems, such as message queues, publish-subscribe systems, and streaming platforms. | ||
|
||
|
||
## AsyncAPI document | ||
An AsyncPI document is a file that defines and annotates the different components of a specific Event-Driven API. | ||
|
||
|
||
## Bindings | ||
A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. | ||
|
||
|
||
## Consumer | ||
In an Event Driven Architecture (EDA), a consumer is an application that listens for a particular event from a broker and reacts to it. | ||
|
||
|
||
## EDA | ||
EDA stands for Event-Driven Architecture, an architectural pattern that structures software systems around event production, detection, and consumption. In an event-driven architecture, components or services communicate by producing and consuming events representing significant changes or occurrences in the system. | ||
|
||
|
||
## Event | ||
An event is a message that provides details of something that has already occurred. | ||
|
||
An Event-Driven Architecture (EDA) uses events to trigger and communicate between services and is common in modern applications built with microservices. | ||
|
||
|
||
## Identifier | ||
This field represents a unique universal identifier of the application the AsyncAPI document defines. It must conform to the URI format, according to RFC3986. | ||
|
||
|
||
## Message-driven APIs | ||
Message-driven APIs, also known as Messaging APIs, facilitate communication between different components or services by exchanging messages. Instead of traditional request-response patterns in synchronous APIs, message-driven APIs rely on asynchronous messaging to enable decoupled and loosely coupled communication. | ||
|
||
|
||
## Microservices | ||
Microservices are a software architecture approach where applications are divided into small, independent services that communicate with each other through APIs. Each microservice focuses on a specific function, allowing scalability, agility, fault isolation, and technology flexibility. | ||
|
||
|
||
## Modelina | ||
Modelina is a library for generating data models based on inputs such as AsyncAPI, OpenAPI, or JSON Schema documents. | ||
|
||
|
||
## Producer | ||
A producer is an application that senses state changes (events) and publishes those events as messages. An event indicates a state change or update triggered by a user's/device's action. | ||
|
||
|
||
## Protocol | ||
A protocol is a set of rules that specifies how information is exchanged between applications and/or servers. | ||
|
||
|
||
## ProtocolVersion | ||
The version of the protocol used for the connection. | ||
|
||
|
||
## Studio | ||
Also known as the AsyncAPI studio is a tool that allows you to develop an AsyncAPI document, validate it, preview it, convert it to the latest version, and visualise event flows. | ||
|
||
|
||
|
||
|
||
<!--- | ||
TODO: I need help deciding what these terms could be fit for and will appreciate any help or suggestions I can get. | ||
|
||
AsyncAPI specification | ||
AsyncAPI spec | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Let's stick to the full spelling of "AsyncAPI specification" and only list/define that term in this Glossary. Adding the abbreviation of "AsyncAPI spec" would be superfluous. 😄✌🏽 |
||
AsyncAPI file | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The history behind all these variations is that for a while, folks were saying BOTH Finally, sometime late last year the community decided to stick to one term: |
||
AsyncAPI specification file | ||
AsyncAPI instance | ||
AsyncAPI definition | ||
AsyncAPI contract | ||
|
||
Secondly, in writing AsyncAPI, are there any variants? like these: | ||
|
||
- asyncAPI | ||
- Async API | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes! Many people write it INCORRECTLY. 😂 The only correct way to write our oss project name is There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ok. Done this. Let me know if this is something we want to do or if there are other ways to make this obvious; that'll be great too. Also, I'll like to know what flavour of Markdown we use for writing docs. It's my first time using the "Remember" tag. I kept spelling it with low caps "r" and wondered what I did wrong. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sure! A remember block could make great sense since this is a VERY common mistake :D |
||
I noticed that in different cases, it is spelt differently. Do we want to specify anything? | ||
|
||
Finally, I'll apprecite new words to be added. Thanks | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||
|
||
--> | ||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Heyo, your directory structure is wrong because it's missing the
Community
content bucket folder. 😄 We are storing our Style Guide in theCommunity
content bucket so your directory needs to be:asyncapi.com/docs/community/style-guide/glossary
.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P.S. I didn't mention this before because we JUST merged our new
Community
content bucket into the docs this week... but now that we have a LIVECommunity
content bucket in the docs, we actually should be authoring community docs directly in the/Community
repo. (We actually have similar behavior/process in place for tools and specification docs too! Tools and specification docs are actually stored in their repoes and then copies to our website repo docs.)I would work on your second draft and create a NEW PR in the community repo when you have it ready to review.
Please let me know if this doesn't make sense!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I will need more explanation on this.
I currently have the following and the docs resides inside the 'Pages' folder as shown in the screenshots below.
second screenshot.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, exactly! The sub-folder
community
inside the/docs
directory is where the Style Guide will live.That said, please note that your glossary document should be inside a NEW sub-folder of
Style Guide
. The URL for your document should be as follows:asyncapi.com/docs/community/style-guide/glossary.
Please let me know if this makes sense, we can always have another quick call too 💜
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I noticed that, too and fixed it up. Thanks for calling that out.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SOOOO CLOSE, @CynthiaPeter. 😄✌🏽
1
Please note, however, that the sub-directory
style-guide
is missing a dash to separate the words.As noted above, the URL for your document should be as follows:
asyncapi.com/docs/community/style-guide/glossary
.2
Your new sub-directory
style-guide
is missing it's ownsection.md
andindex.md
files. Sub-directories need those elements too. (please let me know if this doesn't make sense!)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you, @alequetzalli
I fixed these.
However, is there a guide on how we decide what goes into the _section.md and index.md page?
And if you have the time, I'd like to connect and have a call to talk about this and the onboarding guide. I have some drafts and ideas, but I am not exactly sure how to go about it.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, there is def best practices on what you need to place in both those files. Let's go over this again in a call 😄.
I see you sent me a DM to pick a day/time for that call, so I will follow up with you offline to help unblock you.