Using SwaggerSocket in Atmosphere - Atmosphere/atmosphere GitHub Wiki

The Atmosphere Framework includes [SimpleRestInterceptor] (http://async-io.org/apidocs/org/atmosphere/interceptor/SimpleRestInterceptor.html) which enables the existing REST services to be transparently invoked over Websocket.

Default data binding

This binding describes how REST requests and responses are represented in Websocket messages. It is originated from SwaggerSocket and has been simplified and enhanced from its initial version.

This binding has the following characteristics.

  • Each request contains the method, path, and optional type and data.

  • Each request may be sent with a unique-ID for the client to correlate responses to its requests.

  • The content-type header can be optionally supplied if the content is present.

  • The accept header can be optionally supplied if the response is expected.

  • Arbitrary Http headers are supported, but they may be omitted if thet are not part of the application semantics.

  • The content entity can be optionally supplied following the envelope.

  • A large message can be transported as a series of messages that can be reassembled at the receiving end.

  • The server can periodically send a heartbeat message to the connected clients to keep the connections alive.

The following message format is used for this binding. Each message is represented as a text or binary Websocket message. It consists of the headers part encoded in json and the optional content part which follows the headers part.

Format: General Syntax

{"id": "identifier", "code": status_code, "method": "method", "path": "path", "type": "type_value", "accept": "accept_value", "headers": headers_map, "continue": continue} content

where

  • identifier represents an identifier for the request message which is used in any response message to refer to the original request message,

  • status_code represents the status code of the response message.

  • method represents the request method,

  • path represents the request path,

  • type and accept represent the optional content-type and accept header values.

  • headers_map represents the optional headers other than content-type and accept headers.

  • content represents the optional content entity.

  • continue represents the optional boolean value which indicates the message continues, in other words, followed by another message.

Samples

Atmosphere's samples include cxf-greeter-swaggersocket. This sample demonstrates how this interceptor is used to enable DefaultApi to support SwaggerSocket. Some operations perform plain request-response operations, and some utilize an underlining WebSocket connection to publish and deliver responses asynchronous.