REST Channels: HTTP Channels with JSON support

by Kris ZypSeptember 2nd, 2008

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:

	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:

JSON Format Property Definition
event This defines the method or verb that effectively modified data:

  • put - The resource has been modified, the new content should be included.
  • post - A new resource was added to the system, the content of the new resource should be included.
  • delete - The resource was deleted.

Note that the resource modification does not necessary have to be a result of an actual HTTP request with the given method, but the event indicates that the change was effectively the same as the result of the indicated HTTP method. The data modification could have been the result of internal processes or another RPC action.

source On modification notification messages, this property refers to the resource location that was modified. This is a path, resolvable as a URL relative to the location of the requesting page.
result On modification notification messages, this property provides the new representation of the modified object. This is not necessary when the event was a delete

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

JSON Format Property Definition
target This defines the target path of the resource that was requested
method This defines the method/verb to be executed. This can be get, put, post, delete, or any other available methods. This property is optional (it may be omitted if the client only wants to make a subscription without requesting any data).
subscribe This property indicates whether the client wants to subscribe to the requested resource. This can take two values:

  • * - This indicates that the client desires to subscribe for notifications of any data changes made to the target resource (it is conceivable that in the future more specific subscriptions could be made for certain types of data changes).
  • false - This indicates that the client desires to discontinue a subscription to the requested resource.
content This property provides the data to be applied to the target path. This is the new object data for puts and posts
params This is an optional property that when present should be an array that provides additional arguments for the execution of the method.
id This is an optional identifier that can be used for correlating requests with responses over transports that do not have specific request-response mechanism (like cross-frame messaging or TCP/IP).

REST Response Message

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

JSON Format Property Definition
result This property provides the data returned from the requested method execution.
subscription This property is used to indicate whether the subscription request was successful. Two values are acceptable:

  • true - This indicates that the server will notify the client of data modifications for the requested resource.
  • false - This indicates that the server will not notify the client of data modifications.
error If an error occurred in handling the request, the error information can be included in this optional property.
id If the request had an id property, the response should include the same id to correlate the response to the request.
source This optional property indicates the resource that was requested. If no id was provided by the request message, and the underlying transport does not make request/response correlation, this can be used to understand what resource was delivered.

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).


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 
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.


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.

20 Responses to “REST Channels: HTTP Channels with JSON support”

  1. Matthias Wessendorf Says:

    Interesting. However, the demo has a JS error (customerStore is not defined), used FF2.x

  2. Kris Zyp Says:

    Should be fixed now.

  3. Adam Fisk Says:

    Love it. Does Jetty support REST channels on the server side?

  4. Kris Zyp Says:

    Persevere is built on Jetty providing REST Channels support on the server side.

  5. Comet Daily » Blog Archive » Using REST Channels in Dojo Says:

    [...] REST Channels is a Comet protocol for data notifications designed to integrate with a REST architecture. REST Channels leverages the semantics of HTTP messaging and provides notifications of the creation, update, and deletion of resources using REST’s resource identifiers (URI) in order to provide real-time views of data from web clients. [...]

  6. SitePen Blog » When to Use Persevere: a Comparison with CouchDB and Others Says:

    [...] designed for web applications. Notifications can be received from the browser using the REST Channels Comet interface. Persevere’s Comet capabilities are not limited to data changes, but any type [...]

  7. SpringOne 2008 Day 4 « Incremental Operations Says:

    [...] REST Channels - ESB for the web, event pub-sub etc [...]

  8. Tom McGee Says:

    Where is the REST Channels protocol published?
    I would like to do an implementation of it for a project I’m doing or if I can use the REST Channels part of the Persevere project.

  9. Kris Zyp Says:

    This post currently represents the definition of the REST Channels protocol, although I would like to create a more comprehensive documentation of it soon. Dojo provides a client side impl and Persevere a server side impl that can be used as reference implementations if you want to create another implementation. I would certainly be glad to answer questions as well.

  10. Tom McGee Says:

    As I understand it, REST Channels is built on top of the Bayeux protocol. The java implementation of Bayeux looks like it requires the creation of a HTTPSession. Would it be more “REST like” if that state was expressed as a resource?

    Sorry if I sound like the “REST police” :-)

  11. Kris Zyp Says:

    @Tom: REST Channels is not really built on top of Bayeux, but rather is compatible with Bayeux in that it can provide PubSub style eventing and it can be discovered through Bayeux transport negotiation. Of course, the whole concept of Comet, allowing asynchronous messages to be sent from the server is anathema to REST/HTTP, so REST Channels probably shouldn’t be considered RESTful on its own, but is definitely designed to work in conjunction with and extend a REST architecture.

    REST Channels using currently technology where browsers don’t uniformly provide streaming support does a require a “session” (not necessarily a J2EE HTTPSession though), but this is an artifact of browser work-arounds to a create a virtual connection. Outside of this virtual connection (which can be real with WebSocket browsers), no state is required to be maintained.

    One could control subscriptions via resource modifications, but subscriptions are tied to connections, which are transient by nature. All of other transient connection related information in HTTP is delivered by headers, and REST Channels follows suit.

  12. Tom McGee Says:

    I am working on a solution that builds on the ‘Distributed Observer Pattern’ as described here What I’m adding is a proxy observer resource so a browser based client can participate as an observer. The way it would work is (1) a browser client would post a request to a builder resource to create a new proxy observer resource. (2) The builder resource would return the uri of the new proxy observer resource. (3) The client could then subscribe to a event generating resource by sending the proxy observer resource uri. (5) The client could then use reverse ajax to poll the proxy observer resource for the events.

    (1) [client]—-(create request)—> [builder]
    (2) [builder]—-(new proxy observer uri)— >[client]
    (3) [client]—-(subscribe with proxy observer uri)—>[event producer resource]
    (4) [event producer resource]—(event)–>[ proxy observer resource]
    (5) [proxy observer]—(event)—>[client]

  13. Kris Zyp Says:

    @Tom: Does REST Channels not follow the “Distributed Observer Pattern”? If so, where does it differ? In our example we used “/channels” as the event producer resource, if I understand the analogy correctly.

  14. Tom McGee Says:

    Yes I think REST Channels does follow the “Distributed Observer Pattern”.
    What I’m trying to do is an implementation of that pattern that keep application state in a resource. In other words no HTTPSession. That is why I am adding the “Proxy Observer Resource” into the design. The proxy observer resource hold the state.

  15. Kris Zyp Says:

    @Tom: With REST channels, the assumption was that the users would be indicating their desired subscriptions while they were requesting the desired resources. This means the state of the subscriptions for a given client is intrinsically transient. One of the primary goals of REST is minimizing a server’s requirement to hold state information by differentiating between persistent state, and keeping transient state’s scoped to connections. Modeling transient state with resources is actually completely anathema to REST, since it broadens the longevity of the state information about subscriptions. Therefore, if subscriptions are transient aspect of a user’s interaction with the server, the most RESTful thing to do is to model that state with minimal longevity mechanisms (ideally with connection metadata, but in the limited realm of current day browsers, using sessions for the time being)

    However, perhaps the paradigm that you are more interested is actually having subscriptions (or sets of subscriptions) be modeled as persistent resources (observer resource), where the user chooses an existing subscription rather than creating one. This is a compelling approach, although it could be limiting or highly complex to choose an appropriate observer resource if there is a large number of possible permutations of different resource subscriptions. That is, if a client may be subscribing to various different resources in way that it is difficult to predict (and they are in the browser, so they must connect to a single notification end-point), having observer resources for each combination could become a large, heavy set of different resources with tricky selection techniques. This would also involve switching observer resources frequently if the the client’s desired subscriptions changed frequently.

  16. Nancy Says:


    We are looking to use REST channels for pub-sub and wanted to get performance/load/stress test data showing how REST channels handle large number of clients/channels and updates. We are currently using cometd implementation of DOJO for client side and jetty’s bayeux implementation on the server side, so would like to compare the two techniques.


  17. Nancy Says:

    Hi Kris,

    Can you direct us to the spec (guidelines ) for writing a server side implementation for rest-channels besides Persevere?

  18. SitePen Blog » Using REST Channels with cometD Says:

    [...] REST Channels provides a mechanism for receiving notifications of data changes and integrates Comet-style asynchronous server sent messages with a RESTful data-oriented architecture. Dojo includes a REST Channels client module which integrates completely with Dojo’s JsonRestStore, allowing messages to be delivered through the Dojo Data API seamlessly to consuming widgets, with minimal effort. The REST Channels module will automatically connect to a REST Channels server, like Persevere (which offers REST Channels out of the box). However, existing infrastructure may necessitate the use of an alternate Comet server like Jetty’s cometD server. REST Channels can be used on top of another Comet protocol like Bayeux’s long-polling protocol and with a little bit of reconfiguration, you can use Dojo’s REST Channels with a cometD server to achieve Comet-REST integration. [...]

  19. DA Says:


    to me, REST channels look like an implementation of the “asynchronous REST (A+REST)”-Style described by Rohit Khare in . I am just curious if REST channels are really based on this approach, or if they were developed independently.

  20. Kris Zyp Says:

    @DA: REST Channels was developed some independently, though I have looked at ARREST:

Copyright 2015 Comet Daily, LLC. All Rights Reserved