Does intent-driven API mean the functions names need to sound like intent?

[derberg]

While I love the idea of focusing on intent instead of AsyncAPI spec structure, I'm confused by the API because of function names. Do names need to sound like an intent? for me intent means that "I can do with API what I intend to do, do not have to learn the spec, just need to know the basic elements (channels, messages, etc) and do not need to know where are they in the specification, I mean where in the structure".

Why? because sometimes you can express the same intent using different words, why not just having standard names like getMessages with different options passed as arguments?

For example: clientSubscribableMessages mentioned in @smoya article.

I immediately ask myself:

• what "client"?
• is "subscribable" a real word? 😄

while I could have: getMessages, and I could do getMessages(operationName)

didn't you try to fix the spec confusion around pub sub semantics with the API?

[jonaslagoni]

@derberg good question 😄

Just to expand a bit on the article.

From the perspective of a tool developer if we do getMessages(operationName) you need to learn about operation pub-sub semantics and the problems that come with it.

With the intent API we have removed the confusion offering clear functions where you do not need to know about the specification and its problems.

We have your application (application A) that needs to publish to the channel some/channel/path. However, if you want to describe that with AsyncAPI you need to define it from the external (what we call "client") point of view. Meaning you need to define an operation as subscribing to some/channel/path basically defining it for some other application B ("client" to application A). "Client" might not be the correct term to use, any suggestions?

From the perspective of tooling, we offer the abstractions from the spec through applicationPublishableMessages and clientSubscribableMessages based on what tooling you are creating require. This works nicely with the view parameter some templates have adapted, since it makes it "easier" (or at least should) to understand what is happening in the code, without knowing AsyncAPI in detail.

If we try to map this directly to an AsyncAPI document, we can see that many of the functions access the same data. I.e. for channels that an application publishes over you have applicationPublishableMessages and clientSubscribableMessages which return the same. However, the function name has a different meaning depending on the use case. This was our way of abstracting from the problem 🙂

Did that clarify why we suggested what we did, also in terms of your questions? 🤔 Do you see any way to improve the implicit understanding of the API? 🤔

[jonaslagoni]

there can be also other perspectives if you think about them, there can be a broker perspective too, where you use AsyncAPI to configure a broker and create topics there, and document messages floating in the system. A possible perspective that once was mentioned during SIG meeting.

Hmm... I see your point especially in terms of broker perspective, however, application and client were supposed to cover this as well, we just need some other vocabolary to describe the two perspectives.

About configuring a broker, describing messages in systems, you would still be able to do, cause there you don't care about perspective? You are pushing the spec use-case here IMO and so you must expect tooling to not favor you 🙂

I don't care about whether you describe it for a broker, WS (client/server), etc. For me, on the tooling side, there are only two perspectives (since the current AsyncAPI spec describes a single application).

This means all this comes down to correctly describing application and client.

Does it mean tooling should support it? In my opinion no, just like the app perspective should not be supported as that is not expected from the spec.

Hmmmmm... I see your point 🤔

Just to recap, you think we should remove all the application intents?

[derberg]

Just to recap, you think we should remove all the application intents?

my view on the current design is to remove any intents that have a perspective in the name.

we kind of made a round here and get back into the title for this discussion Does intent-driven API mean the functions names need to sound like intent?

[derberg]

My thoughts in an example:

Instead of 4 different functions: clientPublishableChannels, applicationPublishableChannels(), applicationSubscribableChannels(), clientSubscribableChannels()

Have one function with multiple options:

• channels() - gives you all the channels
• channels('sendTo') - gives you channels that you can send to basing on perspective
• channels('receiveFrom) - gives you all the channels you can listen to

Where the hell is the perspective?

const parser = new Parser('server')

or my preference

parser.setPerspective('server')

Advantages:

• smaller and cleaner API
• you set perspective just once, less error-prone
• much easier to extend with more perspectives, as I do not see only "client"/"server" here but also "broker" that people talk about from time to time ("I just want to document all my Kafka topics in one file and not per app")
• we do not focus much on functions name, but purely on the vocabulary for perspectives and operations

I also do not see a problem if we would have multiple verbs for the same operation and perspective. As long as it is well documented and IDE friendly + makes lives of devs easier, then we should consider that.

[smoya]

@derberg

"Application" and "Client" only bring additional confusion because in architecture with broker in the middle, nobody use term "client", it is just App A, B, C, etc. the app and client terms are specific and will require understanding first, before someone will be able to use the API.

I agree the terminology can be improved. In fact, as per our specification we use the term Application, and Producer or Consumer as aggregates of the first.
Broker could naturally be another aggregate. That perspective would come with few particularities in terms of business logic regarding our spec, logic that would need to be written down and handled at tooling level as well. That's the main reason for including the "perspective" (Are we using that term officially?) as part of the final intent.

there can be also other perspectives if you think about them, there can be a broker perspective too, where you use AsyncAPI to configure a broker and create topics there, and document messages floating in the system. A possible perspective that once was mentioned during SIG meeting.

And that was also contemplated here. We decided that each perspective would have it's own set of intents as well (for the reason I gave in the previous quoted reply).

[smoya]

parser.setPerspective('server')

A quick note here: tooling users might want to use several "perspectives" at the same time so they can, for example, generate documentation or code for several "perspectives" at once. This means we would need to create several parser instances for each needed "perspective".