Story: Eve Helps Chan Fix His Spaceship

1. Info (Metadata about the API):

• Think of this as the name tag on Chan's spaceship. It tells you the spaceship's name and which version it is (like if it's a newer or older model). In our API, the "info" section does something similar. It gives a title and version for the API, like a name tag so everyone knows what they're working with.

2. Channels (Communication channels in the API):

• Imagine the spaceship has different radio stations for talking to different parts of space. Each station (or channel) is for talking about specific things. In our API, "channels" are like these radio stations. They're paths for sending specific types of messages. Each channel is for a different topic, just like how each radio station on Chan's spaceship talks to different planets or stars.

3. Components (Reusable parts of the API):

• This is like having a toolbox on the spaceship. In this toolbox, there are tools and parts that Eve can use over and over for different repairs. The "components" section in our API is similar. It has reusable parts like message definitions and rules (schemas) that you can use many times in different places of the API.

4. Tags (Categorizing operations):

• Tags are like labels on the spaceship's control panel. Each label helps Eve quickly find what she needs to fix the spaceship. In the API, "tags" help categorize different operations, making it easier for people to find and understand what each part of the API does.

5. Operations (Defined actions within channels):

• Operations are like instructions or actions that can be done on the spaceship. For example, there might be an operation for sending a message to Earth. In our API, "operations" are defined within the channels and tell what actions can be done, like sending or receiving messages.

6. Messages (Content of the messages in operations):

• Messages in our story are like the actual words Eve and Chan use when they talk through the spaceship's radio. In the API, "messages" are defined in operations and describe what the messages sent or received look like, including their structure and content.

7. Schemas (Structure of message content):

• Schemas are like blueprints or instructions for how to build or fix parts of the spaceship. They make sure that everything fits together correctly. In the API, "schemas" are in the components section and describe how the message content should be structured, like whether it's a simple text or a more complex list of instructions.

So, in our story, Eve uses all these parts - like the name tag, radio stations, toolbox, labels, instructions, words in their messages, and blueprints - to understand and fix the problem with Chan's spaceship engine. Similarly, in an API, developers use info, channels, components, tags, operations, messages, and schemas to make sure the API works properly and does what it's supposed to do.

---

Module 4:

Story: Chan's Space Message to Eve

*** add reaction ***

1. Writing an AsyncAPI Document from Scratch:

• Setting Up the Basics:

  • Chan begins by setting up his space message plan. He writes:

    asyncapi: 3.0.0
    info:
      title: Sending Signal to Eve
      version: 0.1.0

    This is like Chan saying, "I'm using the 3.0.0 space message rules, and I'm naming my plan 'Sending Signal to Eve.'"

• Creating Channels and Messages:

  • Chan then decides on the path his message will take to Eve. He sets up a channel, like a route in space, and names it userSignedUp with an address Earth/letter. The code looks like:

    channels:
      userSignedUp:
        address: Earth/letter
        messages:
          lettertoEarth:
            description: Communicating with Eve.
            payload:
              type: object
              additionalProperties: false
              properties:
                fullName:
                  type: string
                email:
                  type: string
                  format: email
                age:
                  type: integer
                  minimum: 18

    This part is like Chan detailing the contents of his message – like who it's from (full name), how to contact back (email), and making sure the receiver is old enough (age).

• Setting Up Operations:

  • Finally, Chan adds instructions for how the message should be sent. He writes:

    operations: 
      userSignedUp:
        action: send
        channel: 
          $ref: '#/channels/lettertoEarth'

    This tells his spaceship that it should 'send' messages through the 'userSignedUp' channel.

2. Using AsyncAPI Tools for Validating the Document:

• After writing his space message plan, Chan uses a tool called AsyncAPI Studio to make sure everything is set up correctly. It's like a helper that checks his work to make sure there are no mistakes.

3. Hands-on Exercise:

• Chan wants to practice more. He thinks about adding a new property for a username and creating a new channel for messages to Mars. He updates his document with these new details and then uses AsyncAPI Studio to validate his changes.

In this story, Chan is like a space engineer, carefully crafting and checking his plans to ensure his messages can travel correctly through space to reach Eve and Mars. It's a lot like when you work on a science project, planning carefully and then double-checking to make sure everything will work just right.