[FEATURE REQUEST] HTTP with multiple methods

[KhantParthA]

Is your feature request related to a problem? Please describe.
here in asyncapi 2.0.0 we can not add multiple operations like GET-POST-DELETE-PUT using single operation Binding in a single channel.

Describe the solution you'd like
please add multiple operations - (GET, POST, PUT, DELETE) in same channel
using Operation Binding like "http" in asyncapi version 2.0.0

Describe alternatives you've considered
How it possible to add multiple operations - (GET, POST, PUT, DELETE) in same channel
using Operation Binding like "http" in asyncapi version 2.0.0

Additional context
this is possible

    parameters:
      streetlightId:
        $ref: '#/components/parameters/streetlightId'
    bindings:  
      ws:
        query:
          type: object
          required:
            - companyId
          properties:
            companyId:
              type: number
              minimum: 1
              description: The Id of the company.
          additionalProperties: false
        bindingVersion: '0.1.0'
    publish:
      operationId: turnOff
      bindings:
        http:
          POST:
            type: request
            method: POST
            query:
              type: object
              required:
                - companyname
              properties:
                companyId:
                  type: number
                  minimum: 1
                  description: The Id of the company.
              additionalProperties: false
            bindingVersion: '0.1.0'
          PUT:
            type: request
            method: PUT
            query:
              type: object
              required:
                - companyname
              properties:
                companyId:
                  type: number
                  minimum: 1
                  description: The Id of the company.
              additionalProperties: false
            bindingVersion: '0.1.0'  
      traits:
        - $ref: '#/components/operationTraits/kafka'
      message:
        $ref: '#/components/messages/turnOnOff'```

[fmvilas]

Hi @KhantParthA, I transferred this issue to the bindings repo, as it's a problem with the HTTP binding. Aside from that, I'm curious to understand why would you need this feature? Are you trying to document a REST API using AsyncAPI?

[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 ❤️

[daFritz84]

CoAP (RFC 7252) is a good example. CoAP is designed to allow for REST (GET/PUT/POST/DELETE) and publish/subscribe (OBSERVE) semantics. See also https://coap.technology

I'm currently in need for a specification format for a CoAP and find both OpenAPI and AsyncAPI lacking in some way or another.

[Astiolo]

Having a HTTP binding that doesn't support multiple methods seems like a pretty big oversight to me. I don't think there really needs to be justification for supporting a key feature of the protocol that this is meant to support.

[fmvilas]

Just leaving a thought here. I think we should make the HTTP binding a subset of the OpenAPI specification instead of reinventing the wheel. To be more specific, I think the shape of the HTTP binding should be the Path Item Object of OpenAPI.

[jonaslagoni]

Just leaving a thought here. I think we should make the HTTP binding a subset of the OpenAPI specification instead of reinventing the wheel. To be more specific, I think the shape of the HTTP binding should be the Path Item Object of OpenAPI.

After watching the discussion from the request/reply video I have some things I want to mention from a completely opposite point of view.

I don't think you will find it useable to reuse such a huge chunk of the OpenAPI spec. What would the main drivers be to allow this?

• Reusability

Alright, but The Path Item Object is not meant to be reused, at all. You cant even use a reference in your OpenAPI document if you split it out.

• Tooling

Regardless of which chunks we reuse, tooling would need to adopt AsyncAPI as inputs. I have a hard time seeing how that would be achieved with such a scattered tooling landscape as with OpenAPI. Maybe with the right people on board, it could be achieved.

• Faster adoption of AsyncAPI if you come from OpenAPI

That could be, but try thinking about the open questions that people are faced with below, then I don't think it would improve anything.

• How do you support multiple different versions of the OpenAPI specification through bindings? I.e. OpenAPI v3.0.0, 3.1.0, etc.
• Where does OpenAPI stop and AsyncAPI start
  • @Souvikns question from feat: add support for multiple methods in http bindings #131: payload vs schema - In AsyncAPI we are using payload to define the message and openapi is using schema so it could be confusing to people well versed in AsyncAPI specification.
  • @Souvikns question from feat: add support for multiple methods in http bindings #131: path item object in openapi depends on their server object which is a clash with asyncapi server object

With the changes currently proposed for AsyncAPI 3.0, an important note before showcasing an example, both the client and server are seen as being an application, each having an API. This means that the client (the public API of the server) will have its own AsyncAPI document, and so will the server i.e. how it interacts with the world.

The application that interacts with the HTTP server would be defined as such (omitting the specifics of what payload the messages are, and the definition of servers):

asyncapi: 3.0.0

info:
  title: REST API client example
  description: |
    This application is an example of an HTTP client interacting with an HTTP REST Server.

channels:
  getChannelRequest:
    address: my/custom/path
    message:
      $ref: '#/components/messages/someGetRequestMessage'
  getChannelResponse:
    address: null # It is replied on the same channel address, not a separate one.
    message:
      $ref: '#/components/messages/someGetResponseMessage'
  postChannelRequest:
    address: my/custom/path
    message:
      $ref: '#/components/messages/somePostMessage'
  postChannelResponse:
    address: null # It is replied on the same channel address, not a separate one.
    message:
      $ref: '#/components/messages/somePostResponseMessage'
      
operations:
  postOperation:
    action: send
    description: This application is sending a `post` request to an HTTP server
    channel: '#/channels/postChannelRequest'
    bindings: # This is just my assumption as nothing is concrete
      http: 
        method: POST
    reply:
        channel: '#/channels/postChannelResponse'
  getOperation:
    action: send
    description: This application is sending a `get` request from to an HTTP server
    bindings: # This is just my assumption as nothing is concrete
      http: 
        method: GET
    channel: '#/channels/getChannelRequest' 
    reply:
        channel: '#/channels/getChannelResponse'

components:
  messages:
    ...

For the server, it would basically mirror the operation actions and use receive instead:

operations:
  postOperation:
    action: recieve
    description: This application is receiving a `post` request from an HTTP client
    channel: '#/channels/postChannelRequest'
    bindings: # This is just my assumption as nothing is concrete
      http: 
        method: POST
    reply:
        channel: '#/channels/postChannelResponse'
  getOperation:
    action: recieve
    description: This application is receiving a `get` request from an HTTP client
    bindings: # This is just my assumption as nothing is concrete
      http: 
        method: GET
    channel: '#/channels/getChannelRequest' 
    reply:
        channel: '#/channels/getChannelResponse'

So the question comes down to, would this be okay? Even without reusing large chunks of the OpenAPI spec?

Also, think we can do a lot to help people get started and work with AsyncAPI if they come from OpenAPI. Among other things are:

1. Creating an OpenAPI to AsyncAPI converter to verify and validate as we go, that the HTTP bindings support what is necessary to define HTTP-type operations based on the OpenAPI document. That way we don't reinvent the wheel, even though we don't necessarily reuse the entire wheel.
2. Creating an AsyncAPI to OpenAPI converter which can be used to enable usage of OpenAPI tooling. Of course this only works for APIs that use the HTTP protocol.
3. Kinda a hack, but possible with ^ solved, we can create a wrapper for most OpenAPI tooling so you give in an AsyncAPI document, which is converted to OpenAPI and then run through the tools.
4. Adapt the existing HTTP code generators that OpenAPI uses and remake them into templates for the AsyncAPI generator.

cc @fmvilas @Souvikns @KhantParthA @daFritz84 @Astiolo would this suit your needs or do we need something extra?

[fmvilas]

Yeah, @jonaslagoni. I think your comment is spot on. There are a few things to consider though:

1. What about those who have hundreds or thousands of OpenAPI files? Are they going to convert all the files? Are these files easy to find so they can run something like "convert all the OpenAPI files of my company"? Tooling is helpful but it can't solve every problem.
2. What about those using OpenAPI in 3rd-party services like gateways? These 3rd-party services don't understand AsyncAPI yet so they would need to maintain and keep developing the OpenAPI file along with the transformed AsyncAPI file. Tooling is not a solution here either.
3. If we create our own way to define REST APIs, aren't we reinventing the wheel?

Anyway, things to think about for sure.

[Souvikns]

According to this issue, people just want a way to define multiple methods in HTTP bindings (which is something even I want), and only when we reuse openapi, do we have doubts about reusability, tooling, and other stuff. We can just model our HTTP binding by taking some ideas from open API if we feel so.

I think we will have more problems if we try to reuse openAPI, maybe reinventing the wheel is the best option we have 🥲

[fmvilas]

I think we will have more problems if we try to reuse openAPI, maybe reinventing the wheel is the best option we have 🥲

Best for who? 😄 Will it make our lives easier or will it make user lives easier? Let's keep thinking. Maybe we shouldn't be putting all this stuff in a binding?

[fmvilas]

@Souvikns I recommend you watch the latest spec 3.0 meeting. I'm sharing a potential new way to integrate OpenAPI and AsyncAPI: asyncapi/community#394.

[ClearEyesFullHearts]

I don't know if it's a resolved matter or not but from a user's perspective (me) I just need the method field of the operation binding object to be moved to the message binding object so that i can use a oneOf there to describe different messages for each method with the correct binding.

channels:
  /ping
    servers:
      - home
    subscribe:
      message:
        oneOf:
          - $ref: '#/components/schemas/getMessage'
          - $ref: '#/components/schemas/postMessage'
          - $ref: '#/components/schemas/putMessage'
          - $ref: '#/components/schemas/deleteMessage'

[jonaslagoni]

As of the new request/reply functionality in v3, it is now possible to define multiple operations for HTTP each with different HTTP methods.