fix: revert Kafka operation binding to publish

[dpwdec]

Based on the articles provided by the AsyncAPI org, specifically the Demystifying the semantics of Publish and Subscribe the publish binding documents how you (the client) interact with the documenting application through the messaging channel.

publish means publish an event to the channel and this application will receive it

For a Kafka consumer you should publish to the target channel to interact with a consumer application. Given the operation binding in this specification explicitly describes "consumer" data on the object it seems like it should be using a publish binding in the example to avoid confusion.

I use "revert" here because when this operation binding specification was first added it did use publish but was changed in a later merge and I'm not sure why.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide 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.

[dpwdec]

Hi @dalelane @lbroudoux Is there anything else I need to do with this PR? Otherwise, can I request your review?

[KhudaDad414]

@dpwdec I don't think we have enough information on that example to decide if the application is a publisher or a subscriber. 🤔 So I think both publish and subscribe makes sense there.

[dpwdec]

Hi @KhudaDad414

@dpwdec I don't think we have enough information on that example to decide if the application is a publisher or a subscriber. 🤔 So I think both publish and subscribe makes sense there.

The specifications that describe the binding properties used in the example as groupId and clientId state respectively that they are the

Id of the consumer group.

and

Id of the consumer inside a consumer group.

Based on the above descriptions referencing consumers it seems like the authors of the original specification intended for this binding to be used exclusively by consumer Kafka applications hence the misapplication of the subscribe binding in this case. Could you clarify what context a messaging application would list a Kafka operation with consumer group and client as the subscribe source for a channel? If there is such a case then perhaps the above descriptions of the binding needs to be updated to account for this?

[KhudaDad414]

@dpwdec I think the specification of the bindings is a little bit off here. 🤔

we can have clientId whether the application is a consumer or a producer.
you are right about the groupId, it only applies to consumers I guess.

speaking from my limited knowledge of kafkajs so I can definitely be wrong here.

[dpwdec]

@KhudaDad414 Yeah, I'm speaking from limited experience as well, I guess I feel that as we are the "users" for these sorts of bindings for documentation and tooling, if they are ambiguous to both of us they at least need to be updated somewhat 😅

What would the operation binding mean if just clientId were configured under subscribe for a producer to a channel?

Seems like the clientId here is related to the consumer group. But wondering if there's another use case you've seen that uses the clientId separately? What did that look like architecturally?

[KhudaDad414]

@dpwdec

What would the operation binding mean if just clientId were configured under subscribe for a producer to a channel?

I mean If I have multiple producers and I want to differentiate between them to know what message is being produced by which producer, having a clientId would definitely be a good practice here. Although it is not required but I can totally see how useful it can be. based on what I read here it is even recommended.

Seems like the clientId here is related to the consumer group. But wondering if there's another use case you've seen that uses the clientId separately? What did that look like architecturally?

Your are right. a combination of groupId and a clientId would indicate that the client is a consumer. but what if they are both under subscribe (just like how it is now)? what would it mean for tooling? is it invalid? 🤷

[lbroudoux]

Hi there,

First and foremost, I have to admit I've never been at ease with both groupId and clientId and I think I'm the one you changed the operation type lately as I usually adopt the API consumer point-of-view when I'm looking at an AsyncAPI spec (think it's a bias, sorry).

I tried to have a thorough read of the above messages and I tend to think that different interpretations could fit. It really depends on who is the reader of the AsyncAPI document. Let me explain what I have in mind:

Case with subscribe operation

If you're in charge of implementing the application that owns this API then subscribe means that you need to publish messages and you may only need the clientId to generate some conf/code (but then its definition its not correct)

If you're in charge of consuming the API, then subscribe means that you need to consume messages and maybe the API owner has restricted the possibilities with pre-defined groupId and clientId you have to stick to.

Case with publish operation

If you're in charge of implementing the application that owns this API then publish means that you need to consume messages and maybe you should use the defined groupId and clientId.

If you're in charge of consuming the API, then publish means that you need to publish messages and maybe the API owner has restricted the possibilities with pre-defined clientId (but then groupId can be used by the other side, and the definition of client is still awkward).

If we look at the above cases, there are two of them where groupId + clientId is valid:

• subscribe with groupId + clientId => they are useful for people consuming the API
• publish with groupId + clientId => they are useful for people implementation the application

I agree that it is full of ambiguity and needs clarification ... But to me, this really lies to the target audience of an AsyncAPI specification documentation: is it expected to be used for implementing the application holding the API (and thus giving constraints to code/configuration) OR to the people who will later consume this API?

I personally prefer the second option (targeting people who will later consume this API) and so I tend to think that subscribe with groupId + clientId is valid. But ... 🤷

[dalelane]

Apologies for coming to this a little late.

As @lbroudoux says, I think the confusion here is another symptom of https://www.asyncapi.com/blog/publish-subscribe-semantics

I think there are people who have written AsyncAPI docs from both perspectives (I know I certainly have), and several tools that use AsyncAPI to generate code can treat it from either perspective (see https://www.asyncapi.com/blog/publish-subscribe-semantics#what-does-this-mean-for-using-the-spec for examples)

So my instinct is to allow groupId for both publish and subscribe

[github-actions]

This pull request 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 pull request, add a comment with detailed explanation.

There can be many reasons why some specific pull request 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 pull request forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[derberg]

I guess this one can be closed?

[dpwdec]

Sorry for not being very responsive on this. In terms of closing the PR would it be constructive to include both perspectives with a note based on what @lbroudoux has written (seems well considered and helpful to future users). Unless this sort of confusion will be solved the semantics changes in AsyncAPI V3?

[lbroudoux]

I agree that we can close this PR. Maybe reference the conclusion of this discussion in the README for Kafka bindings? WDYT?

[derberg]

closing
please feel free to follow up with any additions and clarifications in the binding