"Websocket" communication specification. Alternative way to communicate


Hi everybody,

I want share with you my own (and my friends and collegues) vision on websocket feature.

WebSocket itself is not replacement for REST of course. It’s different technology. We saw already existing modules and plugins, which implement REST on top of WebSocket. But it’s all about stateless (REST) communications and it is not what we are thinking of and not what we really need for specific tasks.

So the question I guess is not only about websocket, but about something that can be “alternative” for REST. Maybe “alternative” is not correct word. But something new, that can be used a little bit different. Another/additional way to communicate.

What I want to see in specification is support for stateless communications.
How it will look like in test API environment (IMHO and will be great to discuss it together to understand if its true or not):

  • Specify endpoint. Path is optional. It can be simple IP-address, or even existing websocket connection pool (whatever). But to simplify for the first, we can use the same like URI. You need to think of it like it happens not only in browser. It can be mobile or even something else if it exists.

  • When websocket connection is opened, we can send and receive messages now

  • Sending and receiving messages happens asynchronous and a bit different from REST. For example, in REST, when client sends GET request, then he waits for response from server for this GET request. If connection if timed out, for example, and client does not get response from the server, then client needs to resend this GET request again. But it is not true for “websocket”. In websocket it can happen like that: when connection is dropped (timed out), client reopens websocket connection and receive response from the server, because server is already knows that client didn’t received this response yet. It is the one of possible scenarios. Everything depends on the specific task.

  • So the next rule is: client can receive messages even without sending any requests. It can be some status messages, chat messages, or whatever you want.

  • This is full duplex connection. So it’s two way communication. Client can send messages and receive response for it. Can send messages and not wait for response (unbelievable situation, but why not). Client can wait for messages from server and not send any request to server. When it receive message from server, then it can send back to server response message.

  • Websocket connection is alive for the whole runtime lifecycle of the application. This is the main goal in most scenarios

  • We have new keyword - “message”. It is not request or response. It is message. And we need also mechanism to answer with messages to some messages, if we need it, in any direction.

Next step can be examples of API source JSON/WHATEVER FORMAT. I will prepare it and share with you also.

This is how I see this new feature. Will be great to discuss it and find the way to implement it.
I am 100% ready to work on it. So my own human/developer resources are shared with you.

With best regards,


this is good article to understand the difference

and understand that it is not really replacement of REST, but simply another technology to communicate

this is very good presentation also - https://www.youtube.com/watch?v=B-ElrhYxPQU - on 25 min they talk about SOAP on websocket. very interesting to investigate


WSDL - can be the real answer. so point may be to extend raml to support WSDL.
What do you think about it?


I don’t think WSDL makes much sense in the context of RAML. RAML already supports the definition of entities serialized in JSON or XML and can define resources as well, so WSDL doesn’t add much.

This said, I’m super supportive about the idea of being able to specify the “streaming” section of an API with RAML, be it websockets, long-polling or any other asynchronous request/response mechanisms.

To me what we need is a way to:

  • tag a resource path as streaming,
  • specify for this resource the supported message bodies, both for client and server, with the capacity to tag a body as a response to another.

@usarid thoughts?


The tagging could be done using annotations right? So something like

  (streaming): ...


Sure, but this means that it’s up to everyone to make up their own annotation. Also, how would you associate entities with this resource?

That’s why I’m unsure that using what’s currently in RAML 1.0 is enough.


mhmhmm - we actually thought about introducing some OOTB annotations for specific tooling already. that way we can actually try some things out first before changing something in the spec


Sounds great.

I bet on try to implement it from some point. I understand that we can use annotations (that maybe not solving everything, but something can be done - why not ).

Well… If I can describe some example service with annotations, then what gonna be next step? Write some tool, that will work with this annotations, or extend some existing tool?