HTTP channel binding should include a path parameter

[jmcx]

Reason/Context

The Kafka and googlepubsub bindings let you specify the topic as a separate attribute, e.g. for Kafka:

channels:
  orders:
    bindings:
      kafka:
        topic: 'kafka-orders-topic'

For the HTTP binding, you must rely on the channel name to define the HTTP path. But the HTTP path can be long and technical and contain lots of slashes, meaning it isn't always very human readable, e.g.:

channels:
  /path/path/something_here/somethingelse/orders:

This also makes it impossible to define a channel once but bind it to different servers with different protocols, if HTTP is one of those.

Description

Would be great to have a path attribute for the HTTP binding so I can have a nice name for the channel and different value for the path, e.g.:

channels:
  orders:
    bindings:
      http:
        path: '/path/path/something_here/somethingelse/orders'

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

This also makes it impossible to define a channel once but bind it to different servers with different protocols, if HTTP is one of those.

this is a very interesting use case, can you please elaborate more. So you have a channel, and in the channel you specify servers and point to 2 different servers? like http and kafka for example? and path and topic are different? Why not defining 2 channels? just to avoid repetition?

[jmcx]

Hi @derberg. To be fair, this is based on the hypothetical use case I described in my blog post, in which the idea was to have a single conceptual channel that provides the same kind of events (orders), but can come from different servers. Maybe does not match a real life use case. This is the definition of channels that could have been factored into a single channel if the HTTP path could be defined separately:

channels:
  orders:
    description: Kafka topic to which orders are produced
    servers:
      - kafkaserver
    subscribe:
      message:
        $ref: '#/components/messages/order'
  /orders/order.json:
    description: REST API endpoint that responds with an order
    servers:
      - httpserver
    subscribe:
      message:
        $ref: '#/components/messages/order'
      bindings:
        http:
          type: request
          method: GET
  orders-gcp:
    description: Google pub/sub topic to which orders are produced
    servers:
      - googlepubsub
    subscribe:
      message:
        $ref: '#/components/messages/order'
      bindings:
        googlepubsub:
          topic: projects/jmcx-asyncapi/topics/ordersgcp

Also, conceptually I thought there was some similarity in being able to define the Kafka or PubSub topic name and the HTTP path explicitly, rather than only deriving the HTTP path from the channel name. I expected it to be possible for HTTP too. Also, having a potentially long and complex URL path as the key for an object in YAML feels kinda strange to me. This is probably very subjective :)

[derberg]

If this is purely style and clean readability related, it should be fixed in few months with AsyncAPI 3.0 where channels will no longer use paths or topic names as channel names. You will provide channel name separately, and path/topic will go under address. So might be that this change will be obsolete. And since there is no real production use case, maybe better to wait?

[jmcx]

Works for me, sounds like it is fixed in 3.0 so we can close this issue 👍

[derberg]

thanks for starting the conversation 🍺