Identify library parser API intents

[smoya]

We want to start defining the new Intent-Driven API for the parser(s). In order to achieve that, we would first need to identify all the possible intents a parser would have.

An intent means a user intention. For example, instead of exposing an API based on a tree-like data structure, such as asyncapi.channel('mychannel').subscribe().message().payload(), we expose clear intents like: asyncapi.getMessagePayloadFor('mychannel', 'subscribe')

The expected outcome for this task is just a list of intents, which could be written in this right issue by now.

Some possible intentions can be deduced by analyzing the following repositories:

Generator

• https://github.com/asyncapi/generator/blob/master/lib/generator.js#L500-L509

Studio

• https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L74
• https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L132-L133

Templates

• https://github.com/asyncapi/generator#list-of-official-generator-templates

Examples:

• Node Template: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/handlers/%24%24channel%24%24.js
• Nats: https://github.com/asyncapi/ts-nats-template/

[asyncapi-bot]

Hey! You've labeled this issue as a Scope. Remember you can use the following command to inform about its progress:

/progress <percentage> [message]

or

/progress <percentage>

A mutiline message.
It supports **Markdown**.

Example:

/progress 40 We're still figuring out how to implement this. We have an idea but it is not yet confirmed it will work.

/progress 50

A few notes:

* We got this figured out :tada:
* We're going to use [this library](#link-to-website) to avoid losing time implementing this algorithm.
* We decided to go for the quickest solution and will improve it if we got time at the end of the cycle.

---

🏋️‍♀️ See the progress on the Shape Up Dashboard.

[jonaslagoni]

Intents in ts-nats-template
more... indicates that it is used in the majority of files and not only those who are listed.

• whether the AsyncAPI document contains specific contentType (This is used throughout the template to control which client to use (the underlying client use a different client based on payload))
  https://github.com/asyncapi/ts-nats-template/blob/762e166b56fb58bd8a24f7ee649e6026b4d57d6f/utils/general.js#L51
  more...

• Get the title of the API

• Get the version of the API

• Get the description of the API
  https://github.com/asyncapi/ts-nats-template/blob/master/template/package.json.js
  https://github.com/asyncapi/ts-nats-template/blob/master/template/README.md.js

• Get the message payload type for specific operation in specific channel
  This means either resolve to TypeScript type or resolve to a model name generated using
  https://github.com/asyncapi/ts-nats-template/blob/master/components/test/publishSubscribe.js
  https://github.com/asyncapi/ts-nats-template/blob/master/components/test/requestReply.js
  more...

• For each channel, get the message payload example for specific operation
  https://github.com/asyncapi/ts-nats-template/blob/master/components/test/publishSubscribe.js
  https://github.com/asyncapi/ts-nats-template/blob/master/components/test/requestReply.js

• Channel has some operation (i.e. hasPublish)
  https://github.com/asyncapi/ts-nats-template/blob/master/components/channel/general.js
  more...

• Message does not have null payload
  https://github.com/asyncapi/ts-nats-template/blob/master/components/channel/reply.js
  more...

• Get channel description for documentation

• Has specific NATS binding
  https://github.com/asyncapi/ts-nats-template/blob/master/components/channel/request.js
  more...

Extended intents
Intents that are not really in scope for the parser (could be) but are just added to make sure they are described.

• Do something per channel/parameter and map/join them together
• Get actual parameters from received channels vs specified channels
  https://github.com/asyncapi/ts-nats-template/blob/master/components/channel/ChannelParameterUnwrap.js

[jonaslagoni]

java-spring-cloud-stream
more... indicates that it is used in the majority of files and not only those who are listed.

• Get the title of the API

• Get the version of the API

• Get the description of the API
  https://github.com/asyncapi/java-spring-cloud-stream-template/blob/master/template/README.md

• Get the message payload type for the specific operation in Java

• Get the specific binding

• Get the specific extension

• Figure out if operation has multiple messages
  https://github.com/asyncapi/java-spring-cloud-stream-template/blob/master/filters/all.js
  more...

[smoya]

/progress 25 We started listing the intents we can find in https://github.com/asyncapi/ts-nats-template repo.

[smoya]

nodejs-template

• Get title, version and description of the API for filling data in the package.json file: https://github.com/asyncapi/nodejs-template/blob/HEAD/template/package.json#L2-L4
• Get the server protocol to:
  • install the required npm packages: https://github.com/asyncapi/nodejs-template/blob/HEAD/template/package.json#L13-L24.
  • import the required packages: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/index.js#L10
• Get the channels name to:
  • generate the router: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/index.js#L12-L14
  • debug logging: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/index.js#L25
• Get the channels name by Operation (publish/subscribe) for configuring the app: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/index.js#L23-L32
• Get message headers to:
  • generate payloads: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/handlers/%24%24channel%24%24.js#L26
  • write code documentation: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/handlers/%24%24channel%24%24.js#L9
• Get message payload to:
  • debug logging: https://github.com/asyncapi/nodejs-template/blob/9759b1e9a3934adabd5aafdb5fe080165f60565c/template/src/api/middlewares/logger.js#L8
  • write code documentation: https://github.com/asyncapi/nodejs-template/blob/9759b1e9a3934adabd5aafdb5fe080165f60565c/template/src/api/handlers/%24%24channel%24%24.js#L13
• Get operation summary to write code documentation: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/routes/%24%24channel%24%24.js#L8
• Get operation id to generate unique handlers: https://github.com/asyncapi/nodejs-template/blob/master/template/src/api/routes/%24%24channel%24%24.js#L13

[jonaslagoni]

Generator

• Get all channels
• Get all messages
• Get component security schemas
• Get component schemas
• Get all object schemas
• Get all parameters
  • this would remove all intent from https://github.com/asyncapi/generator/blob/f91ad342ef774ac3a77f69cc77fc085208f6cd79/lib/generator.js#L408
• Get all schemas
  https://github.com/asyncapi/generator/blob/master/lib/generator.js#L500-L509
  https://github.com/asyncapi/generator/blob/f91ad342ef774ac3a77f69cc77fc085208f6cd79/lib/generator.js#L438
• Get specific server
  https://github.com/asyncapi/generator/blob/f91ad342ef774ac3a77f69cc77fc085208f6cd79/lib/generator.js#L631
• Get the underlying JSON for the document
  https://github.com/asyncapi/generator/blob/f91ad342ef774ac3a77f69cc77fc085208f6cd79/lib/generator.js#L633

[jonaslagoni]

Studio

• Get the underlying JSON for the document
  https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L67
  https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L135
  more...
• Get version of document
  https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L74
• Get title of document
  https://github.com/asyncapi/studio/blob/4f4ea534dfb7a062ea86fcc341123fb3ee1cce9d/src/handlers/apis.js#L132

[smoya]

I think we are fine to move to the next step so we can translate all those intents to actual API methods (if applies).

[jonaslagoni]

/progress 100 defined intent for different use-cases, which should suffice in continuing to the next stage

[fmvilas]

@jonaslagoni @smoya make sure you share the result of this with @derberg and the community on the #tooling channel. It's interesting for other template developers.

[jonaslagoni]

@fmvilas we are just using this initial research to get a grip for #90. This was done to see how the different libraries interact with the parser as it is now.

But we will of course keep the community in the loop as much as possible, but I also feel like we would need to come up with a starting point, something concrete that can be discussed instead of something vague :)

[smoya]

@fmvilas we are just using this initial research to get a grip for #90. This was done to see how the different libraries interact with the parser as it is now.

But we will of course keep the community in the loop as much as possible, but I also feel like we would need to come up with a starting point, something concrete that can be discussed instead of something vague :)

I think we should share right now we just started with the Parser API reshape, that we are in the design step and mention we will keep iterating on #90 so feedback will be welcome.
We can always drop another chat once the design becomes more tangible.

WDYT? @fmvilas @jonaslagoni

[jonaslagoni]

IMO it is a very fine line between spamming and saying something meaningful, and I don't think we have anything meaningful besides what you already posted, that we started on this bet 😄 But of course if you feel like we need to give more info then sure, we can add that 😄

Maybe better to write too much then too little? idk 😄

[fmvilas]

When in doubt, favor the overcommunication. Just use the right channel (#tooling) and keep it on a thread. If people don't want to follow your stuff, they can turn off notifications or leave the channel. Also, keeping everything on a thread prevents it from triggering a notification for each message.