-
-
Notifications
You must be signed in to change notification settings - Fork 3
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: adding content for module 3 #9
Open
TRohit20
wants to merge
13
commits into
asyncapi:master
Choose a base branch
from
TRohit20:module-3
base: master
Could not load branches
Branch not found: {{ refName }}
Could not load tags
Nothing to show
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
c5325fe
adding structure of module-3 content
TRohit20 273d9d1
adding the document `structure` content
TRohit20 b409528
Request/reply content
TRohit20 990a623
removing request/reply content
TRohit20 ecf2058
Merge branch 'master' into module-3
TRohit20 1e2fd12
Merge branch 'master' into module-3
TRohit20 513da3d
Merge branch 'module-3' of https://github.com/TRohit20/learning-paths…
TRohit20 3c9fb4d
tw editorial fixes
alequetzalli a4491c5
Update 100-level-AsyncAPI-Intro/step2.md
alequetzalli be14e38
Merge content from PR #5 & #11
TRohit20 45be13d
remove exercises from wrong place
alequetzalli 92d61c3
Apply suggestions from code review
TRohit20 59802cf
Committing suggested changes by Mahfuza based on Sergio's Review
TRohit20 File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,250 @@ | ||
As Eve and Chan begin building a communication system using AsyncAPI inside Chan's spaceship control room, Chan asks Eve if there is a standardized way of defining the communication system or if she defines the communication systems differently based on the particular use case. | ||
|
||
Eve replies that AsyncAPI has a standardized way of defining communication systems. She explains to Chan that the communication system is defined using a specific structure within an AsyncAPI document. As it is much easier to understand things in action, Eve shows Chan how to structure components in an AsyncAPI document. | ||
|
||
## Understanding AsyncAPI components | ||
|
||
- **Info** | ||
|
||
Just as the name tag on Chan's spaceship provides essential details like the spaceship's name and model, the `info` section in AsyncAPI serves a similar purpose. It provides crucial information about the API, such as the title, version, and description. The `info` metadata helps developers understand the basic API details they're working with. | ||
|
||
```yml | ||
asyncapi: '3.0.0' | ||
info: | ||
title: Space Communication API | ||
version: '1.0.0' | ||
description: API for communication between Chan's spaceship and Capuccinova | ||
``` | ||
|
||
- **Servers** | ||
|
||
Imagine that Chan's spaceship communicates with Eve on Capuccinova through various servers. In AsyncAPI, the `servers` section serves to describe both the servers that the application of the API communicates with and the servers that the application itself exposes, such as a websocket interface or HTTP Rest. | ||
|
||
```yml | ||
servers: | ||
production: | ||
host: mqtt://localhost | ||
protocol: mqtt | ||
description: Production server for space communication | ||
``` | ||
|
||
- **Channels** | ||
|
||
The spaceship's radio stations, which correspond to specific topics like communicating with Capuccinova, are similar to the `channels` in AsyncAPI. These channels represent paths for sending specific types of messages. Each channel uses an address, which is a template for the URL of the server, and can have parameters inside curly braces that can be replaced dynamically at runtime. | ||
|
||
```yml | ||
channels: | ||
chatRoom: | ||
address: chat | ||
messages: | ||
chatMessage: | ||
name: ChatMessage | ||
payload: | ||
type: object | ||
properties: | ||
userId: | ||
type: string | ||
description: The ID of the user who sent the message | ||
message: | ||
type: string | ||
description: The chat message | ||
spacename: | ||
type: string | ||
description: The unique spacename identifier for the message | ||
``` | ||
|
||
|
||
## Operations, messages, and schemas | ||
|
||
- **Operations** | ||
|
||
`Operations` in AsyncAPI are like the instructions for the spaceship. They define what actions can be performed within each channel, such as sending or receiving messages. Each operation is associated with a channel and its messages. | ||
|
||
```yml | ||
operations: | ||
sendChatMessage: | ||
action: 'send' | ||
summary: Send a chat message to a specific room | ||
channel: | ||
$ref: '#/channels/roomidchat' | ||
``` | ||
|
||
- **Messages** | ||
|
||
`Messages` in AsyncAPI are the content exchanged during operations, just like the words Eve from Capuccinova and Chan from Brownieterra use to communicate. They describe the structure and content of the messages sent or received. | ||
|
||
|
||
```yml | ||
components: | ||
messages: | ||
ChatMessage: | ||
contentType: application/json | ||
payload: | ||
$ref: '#/components/schemas/ChatMessagePayload' | ||
``` | ||
|
||
- **Schemas** | ||
|
||
`Schemas` in AsyncAPI are like the blueprints for the spaceship. They allows the definition of input and output data types. | ||
|
||
```yml | ||
components: | ||
schemas: | ||
ChatMessagePayload: | ||
type: object | ||
properties: | ||
userId: | ||
type: string | ||
description: The ID of the user who sent the message | ||
message: | ||
type: string | ||
description: The chat message | ||
``` | ||
|
||
- **Components** | ||
|
||
`Component` is like the toolbox in Chan's spaceship. It contains a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. | ||
|
||
TRohit20 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
```yml | ||
components: | ||
messages: | ||
ChatMessage: | ||
name: ChatMessage | ||
title: Chat Message | ||
contentType: application/json | ||
payload: | ||
$ref: '#/components/schemas/ChatMessagePayload' | ||
schemas: | ||
ChatMessagePayload: | ||
type: object | ||
properties: | ||
userId: | ||
type: string | ||
description: The ID of the user who sent the message | ||
message: | ||
type: string | ||
description: The chat message | ||
## Request/reply | ||
As Eve and Chan near the completion of their communication system setup, Eve takes a moment to elaborate on the request/reply pattern to Chan, emphasizing that it is a communication pattern rather than a separate component. | ||
|
||
Eve clarifies to Chan that this pattern involves two key roles: a requestor and a replier. | ||
|
||
In their setup, they establish a channel named `communication` to facilitate requests and enable communication. Now they can stay in touch and communicate about Eve's adventures and Chan's fascinating discoveries during his intergalactic travels. | ||
|
||
```yml | ||
asyncapi: 3.0.0 | ||
info: | ||
title: Eve And Chan's Communication APP | ||
version: 1.0.0 | ||
channels: | ||
communication: | ||
address: /brownieterra | ||
messages: | ||
chit_chat: | ||
payload: | ||
type: string | ||
cool_discovery: | ||
payload: | ||
type: object | ||
properties: | ||
title: | ||
type: string | ||
info: | ||
type: string | ||
date: | ||
type: string | ||
confirmation: | ||
payload: | ||
type: boolean | ||
operations: | ||
sendChit_Chat: | ||
action: send | ||
channel: | ||
$ref: "#/channels/communication" | ||
messages: | ||
- $ref: "#/channels/communication/messages/chit_chat" | ||
reply: | ||
channel: | ||
"$ref": '#/channels/communication' | ||
messages: | ||
- $ref: "#/channels/communication/messages/chit_chat" | ||
sendDiscovery: | ||
action: send | ||
channel: | ||
$ref: "#/channels/communication" | ||
messages: | ||
- $ref: "#/channels/communication/messages/cool_discovery" | ||
reply: | ||
channel: | ||
"$ref": '#/channels/communication' | ||
messages: | ||
- $ref: "#/channels/communication/messages/confirmation" | ||
``` | ||
|
||
Chan wonders how Eve could reach him if he travels around and his address(reply address) is unknown. | ||
|
||
Eve teaches Chan how to set up a communication system and stay in touch even when the reply address is not known. | ||
|
||
```yaml | ||
channels: | ||
communication: | ||
address: /brownieterra | ||
messages: | ||
chit_chat: | ||
payload: | ||
type: string | ||
cool_discovery: | ||
payload: | ||
type: object | ||
properties: | ||
title: | ||
type: string | ||
info: | ||
type: string | ||
date: | ||
type: string | ||
confirmation: | ||
payload: | ||
type: boolean | ||
secret_channel: | ||
address: /cappucinova | ||
messages: | ||
secret_stuff: | ||
payload: | ||
type: string | ||
operations: | ||
sendSecretMessage: | ||
action: send | ||
channel: | ||
"$ref": "#/channels/secret_channel" | ||
reply: | ||
address: | ||
"description": "Consumer inbox" | ||
"location": "$message.header#/secret_reply_channel" | ||
sendChit_Chat: | ||
action: send | ||
channel: | ||
$ref: "#/channels/communication" | ||
messages: | ||
- $ref: "#/channels/communication/messages/chit_chat" | ||
reply: | ||
channel: | ||
"$ref": '#/channels/communication' | ||
messages: | ||
- $ref: "#/channels/communication/messages/chit_chat" | ||
sendDiscovery: | ||
action: send | ||
channel: | ||
$ref: "#/channels/communication" | ||
messages: | ||
- $ref: "#/channels/communication/messages/cool_discovery" | ||
reply: | ||
channel: | ||
"$ref": '#/channels/communication' | ||
messages: | ||
- $ref: "#/channels/communication/messages/confirmation" | ||
``` | ||
|
||
With the final pieces programmed and the communication system in place, Chan gets ready to return home. | ||
|
||
Making a promise to stay in touch, Chan takes off in his spaceship back to Brownieterra. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
You are describing the message and its payload here. However, in the rest of the examples, both are refered from
components
.Maybe makes sense to unify those and use references here as well.
cc @alequetzalli
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 for pointing this out, @smoya!