feat: add HTTP status code

[jonaslagoni]

Description
This PR adds the statusCode property to the message object.

The reason for adding it to the message object and not the operation object, is that it feels more natural, as the status code belong to each message being send.

...
channels:
  HttpCustomersChannel:
    address: /customers
    messages:
      HttpCustomersGetMessageResponse:
        description: OK
        payload:
          $ref: '#/components/schemas/CustomerPaginated'
        bindings:
          http:
            statusCode: 200
            bindingVersion: '0.3.0'

      HttpCustomersGetMessageResponse:
        description: Server error, could not complete request
        payload:
          $ref: '#/components/schemas/SomeError'
        bindings:
          http:
            statusCode: 500
            bindingVersion: '0.3.0'

operations:
  GetCustomers:
    action: send
    channel:
       $ref: #/channels/HttpCustomersChannel
    bindings:
      http:
        method: GET
        bindingVersion: '0.3.0'

Related issue(s)
Fixes #234

[smoya]

The reason for adding it to the message object and not the operation object, is that it feels more

Tell me more, tell me more.

[smoya]

I understand the status code can't exist in the operation since in one channel can coexist several messages (responses) with a different status code each (200, 202, 500...). You won't be able to do this within a single operation.

[smoya]

LGTM! 🚀🌔

[smoya]

Wondering how this will work with Operation Reply objects 🤔

[fmvilas]

Wondering how this will work with Operation Reply objects 🤔

@jonaslagoni I think it's important we clarify this. It would be great to have this info written in the binding document too.

[jonaslagoni]

When you define your application as a REST server i.e. you receive a request where you respond with a reply that has specific status codes it looks like this:

asyncapi: 3.0.0
info:
  title: REST server
  version: 0.0.1
defaultContentType: application/json
servers:
  HttpServer:
    host: 'http://localhost:8080/api'
    protocol: http
    security:
      - type: http
        scheme: basic
      - type: http
        scheme: bearer
        bearerFormat: JWT
channels:
  HttpCustomersChannel:
    address: /customers
    servers:
      - $ref: '#/servers/HttpServer'
    messages:
      HttpCustomersGetMessage:
        payload:
          type: 'null'
      HttpCustomersGetMessageResponse:
        description: OK
        payload:
          $ref: '#/components/schemas/CustomerPaginated'
        bindings:
          http:
            statusCode: 200
operations:
  onListCustomers:
    action: receive
    description: listCustomers
    channel:
      $ref: '#/channels/HttpCustomersChannel'
    messages:
      - $ref: '#/channels/HttpCustomersChannel/messages/HttpCustomersGetMessage'
    reply:
      channel:
        $ref: '#/channels/HttpCustomersChannel'
      messages:
        - $ref: >-
            #/channels/HttpCustomersChannel/messages/HttpCustomersGetMessageResponse
components:
  schemas:
    Customer:
      type: object
    CustomerPaginated:
      type: object

When you define your application as interacting with a REST server as a client where are the one sending the request, nothing changes for the messages nor the status code 🤔

asyncapi: 3.0.0
info:
  title: REST client
  version: 0.0.1
defaultContentType: application/json
servers:
  HttpServer:
    host: 'http://localhost:8080/api'
    protocol: http
    security:
      - type: http
        scheme: basic
      - type: http
        scheme: bearer
        bearerFormat: JWT
channels:
  HttpCustomersChannel:
    address: /customers
    servers:
      - $ref: '#/servers/HttpServer'
    messages:
      HttpCustomersGetMessage:
        payload:
          type: 'null'
      HttpCustomersGetMessageResponse:
        description: OK
        payload:
          $ref: '#/components/schemas/CustomerPaginated'
        bindings:
          http:
            statusCode: 200
operations:
  onListCustomers:
    action: send
    description: listCustomers
    channel:
      $ref: '#/channels/HttpCustomersChannel'
    messages:
      - $ref: '#/channels/HttpCustomersChannel/messages/HttpCustomersGetMessage'
    reply:
      channel:
        $ref: '#/channels/HttpCustomersChannel'
      messages:
        - $ref: >-
            #/channels/HttpCustomersChannel/messages/HttpCustomersGetMessageResponse
components:
  schemas:
    Customer:
      type: object
    CustomerPaginated:
      type: object

In short, it just means that messages referenced in the operation should NOT have statusCode defined, but messages defined in the reply section SHOULD 🤔

How do you folks suggest we clarify the interaction here in a meaningful way 🤔 ?

[fmvilas]

In short, it just means that messages referenced in the operation should NOT have statusCode defined, but messages defined in the reply section SHOULD 🤔

I think we can say that statusCode in the operation messages (not reply) can simply be ignored. We only take it into account inside the reply section. How does that sound?

[jonaslagoni]

@fmvilas added the following as description (feel free to reformat and change it as needed):

The HTTP response status code according to [RFC 9110](https://httpwg.org/specs/rfc9110.html#overview.of.status.codes). `statusCode` is only relevant for messages referenced by the [operation reply object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationReplyObject) as they define the status code for the response, in all other cases this can safely be ignored.

[fmvilas]

Made one more proposal.

[jonaslagoni]

@smoya anything from your side?

[smoya]

In short, it just means that messages referenced in the operation should NOT have statusCode defined, but messages defined in the reply section SHOULD 🤔

I think we can say that statusCode in the operation messages (not reply) can simply be ignored. We only take it into account inside the reply section. How does that sound?

I don't feel this is very user friendly but I can't find a better alternative considering the status code SHOULD be located in the Message Object because the reasons already mentioned.

So 👍 in my side.

[jonaslagoni]

Added the JSON schema changes here: asyncapi/spec-json-schemas#484

Feel free to merge in any order you see fit 🙂

[jonaslagoni]

/rtm