Create WebSocket example

[vit1251]

Could you please provide WebSocket AsyncAPI 2.0.0 complete example.

Right now I totally misunderstand how to describe single channel (i.e. I use only one path "/ws" for example) RPC service with messages like SignUpRequest, SignUpResponse, etc.

[treeder]

I had the same question while working on this demo application: https://github.com/treeder/async-toy-store

I ended up wrapping the messages in metadata that included the channel name: https://github.com/treeder/async-toy-store/blob/master/models/message.go

Not sure how to describe that in AsyncAPI though.

[fmvilas]

Hey folks! I just created a code generator for Node.js and WebSockets. With it, I created an example of an echo client/server using WebSockets. Check it out: https://github.com/fmvilas/asyncapi-websockets-example.

The AsyncAPI file is this one: https://github.com/fmvilas/asyncapi-websockets-example/blob/master/asyncapi.yaml.

Hope it helps!

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[derberg]

It is still needed to have WS example among other examples basing on this thread https://asyncapi.slack.com/archives/C34F2JV0U/p1583757080132600, not to mention that it would make sense to have a documentation that explains the example

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

I think that this could be my next “assignment”. I’d love to do as much as possible here:

• work on a simple sample project that shows the code and how AsyncAPI should look like for sample project
• provide official examples here https://github.com/asyncapi/asyncapi/tree/master/examples
• review existing nodejs and nodejs-ws templates and what are their capabilities at the moment and general state if it comes to websockets
• add dedicated documentation here https://www.asyncapi.com/docs/getting-started
• of course write some blog post about it

What do you think should be my focus. What would you like to see there, what should I showcase? What would you love to get as a user? 🤔

[fmvilas]

I'd make sure the project showcases:

1. How to define a WebSockets API with AsyncAPI.
   1. With multiple channels.
   2. With a single channel but multiple messages.
2. Generate code for multi-channel Websockets API with Socket.io.
3. Generate code for single-channel multiple-messages WebSockets API with raw WebSockets.
4. Generate code for both server and client.

[jonaslagoni]

Would love to see an example for internal communication in terms of Node.js + Socket.io server and client 🙇

[lbdremy]

Nice initiative really fill a hole in the OpenAPI Spec!

I'm trying to model a WS API with the AsyncAPI Spec, I have PUBLISH, SUBSCRIBE but also UNSUBSCRIBE operations, where do you put these operations inside the PUBLISH section? Or am I missing unsubscribe somewhere (https://www.asyncapi.com/docs/specifications/2.0.0#channelItemObject)?

Also, I read your article @fmvilas about organizing your AsyncAPI documents I understood you recommend doing two AsyncAPI documents, one for the client perspective and one from the server perspective. Do you have an example available with the two documents?

I understand in more complex systems with a lot of different consumers/producers it may be interesting to have multiple documents, still, a document to explain the whole system is nice to have. In a WS scenario, what is missing to achieve this, is a field to indicate who can subscribe, and who publishes a message, with WS in mind since there are only two members is easy to identify the member at the other end.

Thanks for your help

[fmvilas]

Hey @lbdremy!

I'm trying to model a WS API with the AsyncAPI Spec, I have PUBLISH, SUBSCRIBE but also UNSUBSCRIBE operations, where do you put these operations inside the PUBLISH section? Or am I missing unsubscribe somewhere (https://www.asyncapi.com/docs/specifications/2.0.0#channelItemObject)?

Yeah, we don't consider unsubscribe as an operation in the spec. An unsubscribe operation is actually a publish to a specific channel with a specific message. It's not the first time someone asks for an unsubscribe operation. This is something we'll have to consider for future spec versions along with request and reply.

Now regarding the file organization, I think in the case of a client/server WebSockets connection, it doesn't make sense to have multiple AsyncAPI files. You could just have one as you do with OpenAPI for instance. The AsyncAPI file represents the server and the publish and subscribe operations represent what your clients can send to you or receive from you, respectively.

The difference with a broker architecture here is that this pattern —even though it's messaging— is not broker-based but instead it follows the "traditional" client/server architecture and the connection is connecting both the client and the server directly, as in an HTTP API. That's why in these cases, I think it makes sense to have only one file for the server and the client just takes it for reference.

Hope that helps :)

[lbdremy]

Yes it helps :) thanks @fmvilas

Now regarding the file organization, I think in the case of a client/server WebSockets connection, it doesn't make sense to have multiple AsyncAPI files. You could just have one as you do with OpenAPI for instance. The AsyncAPI file represents the server and the publish and subscribe operations represent what your clients can send to you or receive from you, respectively.

I agree one OpenAPI file to describe is much better still, in my case, the publish and subscribe operations do not only represent what my clients can send to you or receive from you, respectively. But also the client can publishmessage on a channel for example in a chat room, also a server can subscribe to a channel of the app representing some activities of the app for example "mouse tracking" less common I agree. That's the reason why I was suggesting to have a field to indicate who can subscribe, and who publishes a message. Today I am going to use the summary field and the tags field to indicate this information, it is free text so it is possible but not formalized.

Thanks again for your help :)

[fmvilas]

But also the client can publish message on a channel for example in a chat room

This is the meaning of publish in the server. It means that a client (of that server) can publish a message. It doesn't mean that the server is publishing a message to the client.

also a server can subscribe to a channel of the app representing some activities of the app for example "mouse tracking" less common I agree

Who is "the app" here? Is it the client? If it's the client this case is still a publish. It's the same to say that a server can subscribe to a channel (so the client sends a message there) than saying that a client can publish a message to a channel. Does it make sense?

Usually, the trick here is to think about the communication always from the client perspective. You define what the client can/will do. Therefore, saying that a client can subscribe means that the server is going to publish. Otherwise, why is the client subscribing, right? 😄

[alex-mueller]

Hi,

regarding the initial question I would like to know if I get it right based on the following information:
https://github.com/asyncapi/bindings/blob/master/websockets/README.md

When using WebSockets, the channel represents the connection

That means when I'm trying to model an API between two micro services that is based on Websockets, I essentially ending up defining a single Channel where publish/subscribe probably contain each an anyOf message type, correct?
Should I try to model it the way how @treeder did in his example by adding the channel (or path) to the message payload?
I know, enhancing the docu is still pending but I hope I get at least some feelings about this from you. And sorry if the answer is in the messages above, I read them multiple times and the links but I still had this question ^^

Thanks

[derberg]

I wrote two articles about describing WebSockets with AsyncAPI that should explain the relationship between the two and how to use AsyncAPI to describe WebSocket API. It is based on real WebSocket API (single channel) as I could not come up with a better artificial example. Life is better in creating different scenarios.

• WebSocket, Shrek, and AsyncAPI - An Opinionated Intro
• Creating AsyncAPI for WebSocket API - Step by Step

I want to also record a live stream about the above, to basically provide the same content in audio and video.

I plan one article more + a presentation on a conference. The plan is to write a super basic file (multi-channel) and do some code generation with it. I was thinking about writing a new template from scratch using socket.io (as suggested above) but after playing with https://github.com/asyncapi/nodejs-ws-template I think it is a good and very simple template suitable for education. Let's see where it goes.

Let me know what you think.

If you know a technical writer or just anyone good at docs, that has time to contribute to open-source, please connect us. Would be great if someone can help, grab my content, do some Q&A sessions and create official documentation that we could host on our AsyncAPI website 🙏🏼

[derberg]

• official example for AsyncAPI repo created https://github.com/asyncapi/spec/blob/master/examples/2.0.0/websocket-gemini.yml
• last blog post is here chore(blog): websocket part 3 about code generation website#237 waiting for review and opinions

[derberg]

Last blog post is out https://www.asyncapi.com/blog/websocket-part3

Let me close this issue and please let me know in a new issue if something more is needed

[Jaikant]

@fmvilas We have a microservices based internal pub-sub architecture, and we have webhooks as interfaces to third party applications. I was looking to use AsyncApi as my single source of truth for my internal and external APIs. Looks like that isn't possible yet.

[fmvilas]

@Jaikant Yeah, still not possible. Would be awesome if you create an issue to request for this functionality and maybe even champion it :)