RAML protocols should support Web Socket protocols [ WS, WSS ]

[RobertDeRose]

They support it in swagger and I find it useful.
It would be helpful if you could override the protocol support for an endpoint.

This would mean some APIs endpoints could allow for notifications back to the end-user more easily without having to poll the API.

[thenanox]

+1

[usarid]

How do you suggest we support it? There isn't a universally-accepted structured protocol established on top of websockets, i.e. you get binary 2-way communications once you establish the websocket and it's roll your own after that. An analogy is like describing tcp; instead, RAML describes a protocol on top of tcp, namely HTTP. There are for sure protocols people have chosen to use on top of websockets, so are you suggesting we use RAML to describe one of those?

[RobertDeRose]

So the idea is that APIs like Twitter support streaming endpoints. My thought was you can use RAML to denote that an endpoint allows access through Websockets and you should be able to describe accepted input and output formats.

It was a thought, because I saw that you can use Websockets in Swagger in the schema types. I like the RAML spec better, more flexible and dryer, but this feature was nice when I saw in Swagger.

For reference:

• https://blog.twitter.com/2014/connecting-to-the-pulse-of-the-planet-with-twitter-apis
• https://dev.twitter.com/streaming/overview

[usarid]

What's the reference/link to use Websockets with swagger, please?

On Mon, Jan 11, 2016 at 12:34 PM, Robert DeRose [email protected]
wrote:

So the idea is that APIs like Twitter support streaming endpoints. My
thought was you can use RAML to denote that an endpoint allows access
through Websockets and you should be able to describe accepted input and
output formats.

It was a thought, because I saw that you can use Websockets in Swagger in
the schema types. I like the RAML spec better, more flexible and dryer, but
this feature was nice when I saw in Swagger.

For reference:

https://blog.twitter.com/2014/connecting-to-the-pulse-of-the-planet-with-twitter-apis

• https://dev.twitter.com/streaming/overview

—
Reply to this email directly or view it on GitHub
#217 (comment).

[RobertDeRose]

Swagger Object / Fixed Fields / schemes

[eaglemoor]

up!

[sichvoge]

I think what @usarid tried to get is an example on how that looks like in Swagger. I couldn't find any except the ones that has been annotated on Java classes. Can anyone point to an example.

[eaglemoor]

In web sockets often use a string command or json packages. Raml can write specification by json. I think it's need @RobertDeRose

[RobertDeRose]

The main reason for this request is the concept of streaming APIs such as Twitter's

[robtayl0r]

+1

[niklaszantner]

+1

[coffius]

+1

[eliphatfs]

One year has passed by, and websocket is becoming more and more popular... Is there any progress on this issue now?

[utunga]

+1

[Anton-V-K]

Use RAML for Websocket definition (as an example)

[bali182]

So I think the initial comment suggesting OpenAPI/Swagger support websockets is a bit misleading in my opinion. There is still no official schema for it (You can do it using x-custom-stuff like fields but, no other tool would understand it other that what you write yourself).

Still, you can put your data schemas in the document, and you can also describe routes that can switch to the websocket protocol, but there is no official support, see OAI/OpenAPI-Specification#55.

In terms of suggestions on how to achieve this, here is what you can do with the WebSocket api (I understand this is a generic API describing tool, and I'm quoting a platform specific API, but bear with me):

1. Connect to a ws server - const webSocket = new WebSocket(url, protocols);
2. Listen to messages - webSocket.onmessage = ...
3. Publish messages - webSocket.send(message)

So in my opinion it would be great to be able to describe these in a RAML document:

1. What to connect to
2. What's the schema of the data that can be sent (with mime type)
3. What's the schema of the data that's coming back (also with mime type)

As far as I understand all the above are already possible, the only thing that's missing is a bit of glue between these (new fields for data that you publish, and data you get when you subscribe)

Building higher level abstractions IMO should be out of scope as that would steer the docs towards a specific framework, and there are too many of those.