Swagger for WebSocket services

[sten]

Is there a way to use the Swagger Specification for WebSockets? It seems to be quite bound to HTTP.

[webron]

It's meant to be used for REST APIs so...

On Wed, May 14, 2014 at 6:48 PM, Sten Govaerts notifications@github.comwrote:

Is there a way to use the Swagger Specification for WebSockets? It seems
to be quite bound to HTTP.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/55
.

[webron]

There are possible plans to expand the spec to provide support for it.
For now I'm closing the issue but marking at as a proposal for the next version.

[buremba]

+1

[ralfhandl]

+1: OData has a mechanism to "subscribe" to changes of requested resources, see http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398235.

The ideal notification channel is WebSockets, and we'd like to be able to describe the service-specific shape of that callback/notification mechanism.

[travishaagen]

For barebone requirements, a Websocket has a HTTP endpoint (e.g., /websocket) and supports a few types of JSON messages,

• request / response
• push from client (no response expected)
• push from server (no response expected)

Sample request frame,
{ "cmd": "createUser", "cmdId": "12", ... }

Sample response frame,
{ "cmdId": "12", ..., "status": 200 }

[webron]

Parent: #586

[chrisdostert]

+1

[jroper]

While there may be some higher level semantics that people might want to specify on top of WebSockets, eg subscribing to notifications, I think use cases like that are not really that well understood from a standardisation perspective, and there would be little value in trying to standardise high level concepts like that now, as best practices and idioms are likely to change significantly over time.

I agree with @travishaagen, though I would remove the request/response requirement as it too is also a high level semantic that really has no relation to WebSockets itself.

At the most basic level, I would describe a WebSocket in the same way that a regular HTTP endpoint is described, with a request/response message schema, but unlike a regular HTTP endpoint, on a WebSocket there will be zero to many instances of the request/response messages sent in each direction. From a spec perspective, this could be indicated by simply adding a flag to say that the request and/or response messages are streamed. Further information could be added to indicate what streaming protocol should be used (websockets, SSE, newline separated JSON ala Twitter streaming endpoint style). Higher level semantics such as request/response within the stream, publish/subscribe, etc can in future be built on top of that, but I think starting with just being able to specify that a particular endpoint is a stream is a good start.