Support callback message descriptions

[ghost]

Right now, AsyncAPI does not specify how callback messages should be described.

Some ad-hoc approaches can be used. For instance:

• a topic.publish request's callback message can be described on topic.subscribe (even though it will probably not be conveyed through 'topic')
• a topic.subscribe operation's callback message can be described on topic.publish (even though it will probably not be conveyed through 'topic')
• a separate callback topic can be described (e.g., using Topic Templating as required), together with the message

Hence, for convenience and clarity reasons, a structural callback-specification approach similar to the one proposed in OpenAPIv3 (cfr. spec + example) might be interesting for AsyncAPI as well?

It could look like this:

topics:
  UPDATEARTICLE:
    publish:
      headers:
        type: object
        properties:
          reply-to:
            type: string
            description: Callback Destination to be messaged when the Article was updated
          correlation-id:
            $ref : '#/components/schemas/Correlation-id'
      payload:
        type: object
        properties:
          ...
      callbacks:
        reply:
          '{$request.header.reply-to}':
            publish:
              summary: Reply sent through callback
              headers:
                type: object
                properties:
                  correlation-id:
                    $ref : '#/components/schemas/Correlation-id'          
              payload:
                  type: object
                  properties:
                    success:
                      type: boolean
                    statusMsg:
                      type: string 

Thanks in advance for considering this feature request!

[fmvilas]

I'll dig a bit more on this feature because it's really interesting. Thanks!

[marchon]

The RFC for HTTP [RFC 7231] includes a specification for "Content Negotiation" between the request agent and the response agent. Encapsulating a method of communication of preferred request and response metadata could solve a lot of not yet anticipated future problems.

5.3. Content Negotiation

The following request header fields are sent by a user agent to
engage in proactive negotiation of the response content, as defined
in Section 3.4.1. The preferences sent in these fields apply to any
content in the response, including representations of the target
resource, representations of error or processing status, and
potentially even the miscellaneous text strings that might appear
within the protocol.

+-------------------+---------------+
| Header Field Name | Defined in... |
+-------------------+---------------+
| Accept | Section 5.3.2 |
| Accept-Charset | Section 5.3.3 |
| Accept-Encoding | Section 5.3.4 |
| Accept-Language | Section 5.3.5 |
+-------------------+---------------+

5.3.2. Accept

The "Accept" header field can be used by user agents to specify response media types that are acceptable.

3.1.1.5. Content-Type

The "Content-Type" header field indicates the media type of the associated representation

So: Accept indicates what kind of response from the server the client can accept. Content-type always is about the content of the current request or response.

So if your request has no payload, you don't use a content-type request header.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[smoya]

We can close this as Request/Reply pattern is now a thing in v3.