Skip to content
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: split hello world tutorial into two (send and receive) #2981

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
120 changes: 120 additions & 0 deletions pages/docs/tutorials/getting-started/hello-world-receive-message.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kindly change the folder for these files, as inside markdown.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it, thanks for the reminder!

Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
title: "Receive 'Hello world' message"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the only difference in this document is receive operation and there is a lot of repetition - is it intended? especially that app name is the same Hello world application. Shouldn't it be done like other tuturials for example for Kafka, where first tutorial would be about send message, and the one about receiving would be "extending" the send-one, where you extend the document with additional receive operation (of course still explaining these can be separate)

weight: 35
---

Let's define an application that's capable of receiving a `"hello {name}"` message:

<CodeBlock>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

Let's get into the details of this sample AsyncAPI document:

<CodeBlock highlightedLines={[1]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). That line doesn't have to be the first one, but it's a best practice.

<CodeBlock highlightedLines={[2,3,4]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API.

<CodeBlock highlightedLines={[5,6,7,8,9,10,11,12]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels.

You only have one channel called `hello`, and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in a string format such as `hello {name}`.

<CodeBlock highlightedLines={[13,14,15,16,17]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `receiveHello`.

In the above example, you see that the `Hello world application` is a consumer listening to the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` subscribes to the `hello` topic to `receive` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it.
120 changes: 120 additions & 0 deletions pages/docs/tutorials/getting-started/hello-world-send-message.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
---
title: "Send 'Hello world' message"
weight: 30
---

Let's define an application that's capable of sending a `"hello {name}"` message:

<CodeBlock>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
sendHello:
action: 'send'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

Let's get into the details of this sample AsyncAPI document:

<CodeBlock highlightedLines={[1]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
sendHello:
action: 'send'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The first line of the specification starts with the document type `asyncapi` and the version (3.0.0). That line doesn't have to be the first one, but it's a best practice.

<CodeBlock highlightedLines={[2,3,4]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
sendHello:
action: 'send'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API.

<CodeBlock highlightedLines={[5,6,7,8,9,10,11,12]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
sendHello:
action: 'send'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels.

You only have one channel called `hello`, and you see what message is available in this channel and how it must be structured. The `payload` object defines that the message must be a string and match the given regular expression in a string format such as `hello {name}`.

<CodeBlock highlightedLines={[13,14,15,16,17]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
sendHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

The `operations` section is where you describe what the application is doing. Each operation has a unique identifier for example, `sendHello`.

In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` publishes the `hello` topic to `send` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message from the `hello` channel. In other words, you can say that the `Hello world application` publishes the `hello` topic to `send` the `sayHelloMessage` message. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it.
In the above example, you see that the `Hello world application` is a producer sending the `sayHelloMessage` message to the `hello` channel. In other words, you can say that the `Hello world application` `send` the `sayHelloMessage` message to the `hello` topic. That AsyncAPI document describes what the `Hello world application` is doing, not what others can do with it.

Loading