-
-
Notifications
You must be signed in to change notification settings - Fork 666
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: introducing request/reply #2071
Conversation
✅ Deploy Preview for shimmering-choux-eb0798 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
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.
There are a few corrections for you to address in my preliminary review, make sure to leave you detailed feedback to help get you started. Thank you for your contribution! ✨
Co-authored-by: Alejandra Quetzalli <alejandra.olvera.novack@gmail.com>
Co-authored-by: Alejandra Quetzalli <alejandra.olvera.novack@gmail.com> Co-authored-by: Sergio Moya <1083296+smoya@users.noreply.github.com>
@alequetzalli Hmm, I kinda disagree with you here, cause it is getting started with request/reply in a similar fashion as https://www.asyncapi.com/docs/tutorials/getting-started/asyncapi-documents is. Concept does not make much sense as this is ONLY related to how you do it AsyncAPI and not explaining the underlying concept of how request/reply works 🤔 Guide could be yea, we just don't have anything yet that details how to use specific features in AsyncAPI documents, so it might seem misplaced a bit 🤔 But you have a better overview of the docs and what needs to be where, so just let me know where I should move it to and I will do 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.
- I have reviewed this from my end.
- Had some difficulties and have pinged Alejandra and Fran for the same.
- Please provide your feedback. 🙏 @alequetzalli @fmvilas
|
||
## Multiple messages over the same channel with request/reply | ||
|
||
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation. |
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.
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation. | |
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to explicitly define your operations and which messages are used for each operation. |
I'm having difficulty re-wording this. Please take a look @alequetzalli @fmvilas
Co-authored-by: Animesh Kumar <kumaranimesh923@gmail.com>
weight: 20 | ||
--- | ||
|
||
A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier** which receives the request and responds with a reply. |
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.
A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier** which receives the request and responds with a reply. | |
A quite common messaging pattern is [request-reply](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RequestReply.html). It describes a **requester**, which sends a request message and waits for a reply - and a **replier**, which receives the request and responds with a reply. |
|
||
## Describing a requester | ||
|
||
We are going to use a very simple ping and pong example where a requester sends the ping and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`. |
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.
We are going to use a very simple ping and pong example where a requester sends the ping and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`. | |
We are going to use a very simple ping and pong example where a requester sends the ping, and the responder responds with a pong. To describe a **requester** in AsyncAPI, we make use of an operation that `send`s to the `ping` channel and expects a `reply` over `pong`. |
$ref: '#/channels/pong' | ||
``` | ||
|
||
The `reply` section defines all the necessary information to properly reply to the request, such as where to, and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject) |
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.
The `reply` section defines all the necessary information to properly reply to the request, such as where to, and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject) | |
The `reply` section defines all the necessary information to properly reply to the request, such as where to and with what message. This is just a simple example, but you can check the full list of properties under the [Operation Reply Object.](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyObject) |
|
||
In the simple example above, we saw how you could set up a request/reply pattern across two applications where one application is the requester and the other is the replier. | ||
|
||
However, in an protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables. |
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.
However, in an protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables. | |
However, in a protocol-agnostic world there are many different sub-patterns to the simple request/reply. All of which AsyncAPI v3 enables. |
|
||
The request/reply can also occur over the same channel (for example `/`), which could be HTTP or WebSocket. | ||
|
||
To do this it's as simple as having both channels use the same address. |
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.
To do this it's as simple as having both channels use the same address. | |
To do this, it's as simple as having both channels use the same address. |
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.
- Just had a look at the document.
- Some minor corrections (and a confusion from my end at line 207)
|
||
In some cases, we do not know the reply channel at design time, but instead, it's dynamically determined at runtime. This could, for example, be using the request message payload or header to dictate the response address. | ||
|
||
Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes as you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of where to send the reply is located dynamically in the message header under `replyTo`. |
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.
Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes as you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of where to send the reply is located dynamically in the message header under `replyTo`. | |
Take notice of how we utilize `address: null` to define that we don't know the address just yet. This is just for illustration purposes, but you can also omit the property entirely. We then utilize the [Operation Reply Address Object](https://www.asyncapi.com/docs/reference/specification/latest#operationReplyAddressObject) to define that the address of 'where to send the reply' is located dynamically in the message header under `replyTo`. |
- Is this format appropriate? I think the
where to send the reply
can be wrapped in some quotations or some sort of re-wording can be done but I'm not sure how to approach it. - Requesting your assistance @alequetzalli
|
||
In WebSocket, you often encounter that a channel will contain multiple messages, which means you will have to make your operations explicitly define which messages are used for each operation. | ||
|
||
The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defined the request message among the available channel messages and the same for the reply. |
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.
The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defined the request message among the available channel messages and the same for the reply. | |
The following example is very similar to the above example, with the difference being that we merged the two ping and pong channels into a single one (because they use the same address). The request operation then explicitly defines the request message among the available channel messages and the same for the reply. |
defined or defines? @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.
From a technical point of view, it looks very good. Unfortunately I can't check the spelling.
|
||
## Request/reply with dynamic response channel | ||
|
||
In some cases, we do not know the reply channel at design time, but instead, it's dynamically determined at runtime. This could, for example, be using the request message payload or header to dictate the response address. |
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.
May be mention that this pattern is mostly used when:
You have multiple possible requestor ant want archive that you only receive responses your requested.
With an static response address all possible requestor will receive the responses from every one and need to filter by correlation id, if the received response is one that match a question of your self.
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.
Hint there are even 2 sub types.
Type 1: The process defines an inbox on process startup to receive only responses where it self didt the request for. But also need an correlationId to assign the response to the correct Programm thread. Assuming that the application is not single threaded and blocking.
Type 2: The inbox will be created dedicated for each requests. Than there is no need for an correlationId.
There are plans to rewrite the entire thing into something different by Rohit and @alequetzalli, so I am closing the PR and releasing the content (almost) as is, on my own website so it's not goes to waste and creates a bit of hype 🙂 |
Description
This PR adds a page introducing request/reply concept with AsyncAPI
Related issue(s)
Related to #1434