docs: request/reply

[quetzalliwrites]

Per the scheduled release of spec 3.0 on June 2023, a major update to AsyncAPI docs is needed.

To this end, Jonas added a discussion point for Docs to upcoming Spec 3.0 community meetings. We'll use this time to help guide and support the community contributors who help us document these changes in docs in the weeks leading to the June release.

---

Overview of spec 3.0 release changes that require documentation in this task:

• Request/reply feat: request/response support spec#847

---

⚠️ PLEASE NOTE:
Each of these tasks converted to issues does not imply a single PR; the community should expect to review multiple PRs PER task issue because each spec change introduces updates across all Docs content buckets. (i.e., The request/reply change introduces a need to create a Concepts doc, document further in upcoming new Spec 3.0 docs, and implies huge changes to current tutorials.)

[starlightknown]

heya I would like to take up this issue

[quetzalliwrites]

heya I would like to take up this issue

@starlightknown Join the next Spec 3.0 meeting, so you can ask @jonaslagoni and others how to work on this one. 💪🏿✨

[jonaslagoni]

For this issue, I would suggest we split it up into the following (prioritized in this order):

1. Add request/reply section in the release notes

2. Add a Request/reply concept page

It can live alongside Producer and Consumer because they are individual concepts that can be explained individually. This concept has nothing really to do with the change in the spec, but with explaining the concept around it.

3. Change the Coming from OpenAPI getting started page

This should be changed to show that OpenAPI documents can now directly be described in AsyncAPI because of the new request/reply structure.

@alequetzalli how does this sound to you? Anything you think we are missing? What would you say the rough outlines should include?

[quetzalliwrites]

1. Add request/reply section in the release notes

Will you write the release notes or did you want to team on this too?

2. Add a Request/reply concept page

Yes, I like this idea and was going to recommend the same.

3. Change the Coming from OpenAPI getting started page. This should be changed to show that OpenAPI documents can now directly be described in AsyncAPI because of the new request/reply structure.

Got it! I will need more context around this, but makes sense.

@alequetzalli how does this sound to you? Anything you think we are missing? What would you say the rough outlines should include?

I don't think anything is missing yet, but honestly any outline or rough copy content you send over with info will work. I will also use ChatGPT to get more ideas and will share them with you all in case we can also use ChatGPT as another SME. 😄

[quetzalliwrites]

@jonaslagoni here is the reply ChatGPT sent to my query. I know this is not 3.0 version info, but is any of this useful?

In AsyncAPI, the Request/Reply concept represents a messaging pattern in which a client sends a request message to a server and waits for a response message. The Request/Reply pattern is also known as the Remote Procedure Call (RPC) pattern, where the client invokes a specific function or method on the server and expects a return value.

In AsyncAPI, the Request/Reply pattern is defined using two separate channels, one for the request and another for the response. The request channel is used by the client to send a request message to the server, while the response channel is used by the server to send a response message back to the client.

The AsyncAPI specification defines the Request/Reply pattern using the operation object, which contains the details of the request and response channels, the expected payload, and other relevant information. The operation object includes the following properties:

operationId: A unique identifier for the operation.
summary: A short summary of the operation.
description: A description of the operation.
tags: A list of tags associated with the operation.
message: The schema of the message sent in the request or response.
bindings: The protocol-specific bindings for the request and response channels.
traits: A list of reusable traits that can be applied to the operation.

Here is an example of an AsyncAPI operation object that defines a Request/Reply pattern:

channels:
  user.signup:
    publish:
      message:
        $ref: '#/components/schemas/UserSignUpRequest'
  user.signup.response:
    subscribe:
      message:
        $ref: '#/components/schemas/UserSignUpResponse'

components:
  schemas:
    UserSignUpRequest:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    UserSignUpResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string

operations:
  userSignUp:
    operationId: user.signup
    message:
      $ref: '#/components/schemas/UserSignUpRequest'
    bindings:
      amqp:
        replyTo: user.signup.response

In this example, the user.signup channel is used by the client to send a UserSignUpRequest message to the server, and the user.signup.response channel is used by the server to send a UserSignUpResponse message back to the client. The operation object for this pattern includes the operationId, the message schema, and the bindings object, which specifies the replyTo property to indicate the response channel.

[GreenRover]

The first paragraph is ok. But the rest is only partial correct.

Here the short reply i gave to @smoya via slack:

There are 2 different use cases.
1: WebSocket you have use a single address. So the reply address is defined via channel:
This is the case for all point to point protocols.
https://github.com/asyncapi/spec/blob/next-major-spec/examples/kraken-websocket-request-reply-multiple-channels.yml
2: Messaging using Topic like Mqtt,Amqp,JMS,....:
Here you mostly want to define the reply topic aka inbox of the question asker to be in the message header.
This is the case for all fan out protocols where you not want to fan out the answers to all clients.
You could but than all clients need to filter the responses by their correlationId (you nee to remember the correlationId of all your questions). This would lead in much overhead.
https://github.com/asyncapi/spec/blob/next-major-spec/examples/adeo-kafka-request-reply.yml
Do this makes sense for you?

I would start the second paragraph with some thing like: (sorry englisch is not my native language)

The way how request reply may be used depends highly on the transfer protocols you use.
There is a difference if you have a point to point communication between 2 systems like WebSocket or a communication protocol connection 2-N communication partners like MQTT.

In case that your protocol supports more than 2 communication partners you may want to route the response of your question to just the single endpoint that asked the questions. This is why it is best practice to use a inbox based communication. Where the inbox is a dedicated channel just for this single endpoint. Mostly represented with a channel address starting with a common prefix and having something unique for this endpoint as identifier. Like hostname plus random uuid.

The inbox address needs to be part of the request message to tell the answering endpoint where to send the response to.
An example can be found here: https://github.com/asyncapi/spec/blob/next-major-spec/examples/adeo-kafka-request-reply.yml

In case of a point to point communication there is no need for an inbox. Here you will just define a static response channel.
Like in this example: https://github.com/asyncapi/spec/blob/next-major-spec/examples/kraken-websocket-request-reply-multiple-channels.yml

What both kinds have in common is the need for a correlationId.
Because it may happen that a single requesting endpoint asks more then 1 question in parallel. There is a need to correlation the responses back to it questions. Here it is best practice to let the requesting endpoint generate a random uuid for each question and put this into the request message. The answering endpoint have to copy the correlationId to the answer message to complete the loop.

[smoya]

Adding a Slack thread where I dropped some questions because i was confused with the meaning of our changes regarding the request/reply pattern: https://asyncapi.slack.com/archives/C0230UAM6R3/p1681465268949769

Helpful in building docs that clarify all those concepts, so no more Sergio's confused 😅

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️