HTTP Channels is the proposed Comet protocol for leveraging the semantics of HTTP REST for subscribing to resources and receiving resource/data modification notifications and closely integrates with HTTP. HTTP Channels is most obviously expressed in the MIME-style format used by HTTP, however the MIME format is not necessarily the easiest format to work with, particularly in JavaScript. Fortunately the semantics of REST notifications can easily be expressed in JSON format, which is very easy to parse and handle in the JavaScript environment. This proposed resource modification based notification system, expressible in HTTP/MIME (HTTP Channels) or JSON format will be called REST Channels. JSON-based REST Channels is also well-suited for use with the new Web sockets protocol defined in HTML 5.

The proposed REST Channels protocol is expressed in JSON format by simply putting the resource meta-data properties from HTTP Channels in JSON objects. For example, a notification that a resource was modified with a PUT operation would look like:

{
	event:"put",
	source:"/Person/kris",
	data:{firstName:"Kris",... new version of this object ...}
}

This notification indicates the type of modification that occurred in the event property, the resource that was modified in the source property, and the new content of the resource in the data property.

REST Notification Message

Here is a definition of the JSON properties used for a data notification message by REST Channels in JSON format:

The following message formats define semantic equivalence to HTTP messages, and can be used when duplex RESTful interaction of REST Channels is desired over a non request-response transport.

REST Request Message

REST Response Message

A REST response message should be returned for all REST requests.

JSON is simply an alternate representation for REST/HTTP Channels, not a semantic change; REST Channels messages can be expressed in either native HTTP format or JSON format interchangeably within a session. From a web client, it is generally most efficient to make resource requests in native HTTP format (since this is how the browser sends request, there is no reason to create a layer on top of that), and receive updates in JSON format (since these messages must go on top of the content stream). The proposed MIME format for JSON-based REST Channels messages is “x-application/rest+json” (the x- is for experimental, this would be dropped if it was IANA approved).

Connections

When JSON-based REST Channels is used on HTTP, connection identification is still necessary to correlate individual HTTP subscription requests with the connection that provides notifications. Connection identification with JSON-based messages over HTTP follows the same rules as defined in the HTTP Channels proposal. For example:

First message:

POST /channels HTTP/1.1
X-Create-Client-Id: 3254325325

… Listening for server messages …

Next message:

POST /channels HTTP/1.1
Client-Id: 3254325325

… Listening for server messages …

JSON-based REST Channels will integrate well with WebSocket, and allow HTTP and WebSocket to work together. HTTP can be used for requesting data, and WebSocket can be used for receiving notifications. Their semantics are tied together as a single virtual connection. If you are making data requests on HTTP, connection identification is necessary. WebSocket does not allow user-defined headers, so equivalent URL parameters should be used instead. create_client_id indicates that identifier of the new connection that is being created, and accept indicates the preferred format.

GET /channels?create_client_id=3254325325&accept=x-application/rest+json 
				HTTP/1.1
Upgrade: WebSocket
Connection: Upgrade

… This connection can now receive REST notifications in JSON format …

GET /resource HTTP/1.1
X-Client-Id: 3254325325
X-Subscribe: *

The REST response will come in the standard HTTP response (with a subscription header), and notifications would be delivered on the WebSocket connection.

Other Applications

REST Channels is compatible with JSON-RPC. By including the required properties for both specification, messages can be understood by both protocols. REST requests can be understood as JSON-RPC request, and REST responses can be understood as JSON-RPC responses.

The REST Channels protocol may also be used for frame-based request proxying for cross-site data with the new postMessage API. A frame can act as an HTTP proxy, receiving resource and subscription requests in REST Channels JSON format, and handling the HTTP interaction to the target host. This will be discussed in more detail later.

Implementations

The REST Channels implementation in Dojo 1.2 supports both HTTP/MIME and JSON formats, and integrates with the Bayeux service negotiation. The latest version of Persevere also supports REST Channels in both HTTP/MIME and JSON format. You can also see a simple demonstration of REST Channels with JSON messages.

REST Channels extends the HTTP REST mechanism for asynchronous notifications of changes to monitored data and resources. REST Channels is compatible as Bayeux transport, and can be represented in HTTP/MIME or JSON format.