docs: update parser-api #64
Conversation
magicmatatjahu
requested review from
jonaslagoni,
smoya and
asyncapi-bot-eve
as code owners
docs/v1.md
Outdated
| - messages() : `Message[]` | ||
| - servers() : `Server[]` | ||
| - summary() : `string` | `undefined` | ||
| - tags() : `Tags` | ||
| - type() : `enum{'ClientSubscribing', 'ClientPublishing', 'ApplicationSubscribing', 'ApplicationPublishing}` | ||
| - action() : `enum{'ClientSubscribing', 'ClientPublishing', 'ApplicationSubscribing', 'ApplicationPublishing}` |
There was a problem hiding this comment.
We can include send and receive from asyncapi/spec#618 as it will most probably be in in 3.0.
In fact, I'm thinking if we should just remove the others, or changing the names to ClientReceive, ClientSend, etc.
There was a problem hiding this comment.
I think I would just leave send and receive, removing the others. WDYT @jonaslagoni @fmvilas ? 2.x. users will have to eventually migrate to 3.x if they want a 1:1 match on the action names.
There was a problem hiding this comment.
Yup. I think parser DX should gracefully degrade in v2. Let's not make users choose method names depending on spec versions because they may not know in advance.
| - isApplicationPublishing() : `boolean` | ||
| - isApplicationSubscribing() : `boolean` | ||
| - isClientPublishing() : `boolean` | ||
| - isClientSubscribing() : `boolean` |
There was a problem hiding this comment.
Wouldn't make sense to include isSend() and isReceive() ?
There was a problem hiding this comment.
In 2.x.x these methods would then have a different meaning, so for now I prefer not to add these methods and see how 3.x.x will look like and then we will add the appropriate methods.
There was a problem hiding this comment.
But here we are building an API based on intents, and those are still valid. I think we should add them and, for 2.x.x, return only the value it should be returned, without the application or client perspective.
There was a problem hiding this comment.
Do you suggest isSubscribing, isPublishing?
There was a problem hiding this comment.
No, I suggest we do, at implementation level:
2.x.x:
isSend()-> this.action ===publishisReceive()-> this.action ===subscribe
3.x.x:
isSend()-> this.action ===sendisReceive()-> this.action ===receive
There was a problem hiding this comment.
@smoya Thanks, however in in the 2.x.x we should switch publish/subscribe meaning, because isSend and isReceive describes operation from application point of view, not user, so publish -> receive (user publishes something, so app receives it), but subscribe -> send (user subscribs to something, so app sends it to the user), but I could be wrong, so please correct me.
There was a problem hiding this comment.
Yes, I thought about this but I thought we could just follow the perspective or point of view each spec version has:
- 2.x.x: described from the point of view of the client
- 3.x.x: described from the point of view of the application
However, if we start documenting each method on the Parser-API, it could be convenient to clarify what is the point of view of the API itself, which aligned with >=3.x.x, It would be the application's one.
I think I can agree we should go further and do what you suggest @magicmatatjahu, to be completely strict on meanings and explicitly consider send always means the application is sending a message, no room for interpretation 👍 .
WDYT @fmvilas @jonaslagoni ?
|
/rtm |
|
🎉 This PR is included in version 1.0.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Description
MessageTraitmodelMessageTraitsmodelOperationTraitmodelOperationTraitsmodelMessagemodelOperationmodelSecuritymodelChannelParametermodelRelated issue(s)
Methods introduced in the asyncapi/parser-js#542 PR