LiveResource is a protocol specification and JavaScript reference library for receiving live updates of web resources. It has the following principles:

  • Blend naturally with RESTful API design.
  • Optionally support WebSockets, but do so without abandoning established API principles.
  • Keep it simple. It should be possible to curl for updates.

LiveResource differs from other realtime push solutions by providing a client-side interface modeled around synchronization rather than messaging or sockets. Here’s an example using the JavaScript client library:

var resource = new LiveResource('http://example.com/path/to/object');
resource.on('value', function (data) {
    // the resource's value has been initially retrieved or changed
});

How it works

The client makes a GET or HEAD request to discover the capabilities of a resource:

HTTP/1.1 200 OK
ETag: "b1946ac9"
Link: </path/to/object>; rel=value-wait
Link: </ws/>; rel=multiplex-socket
Content-Type: application/json

For example, the value-wait link indicates that it’s possible to make a GET request that hangs open until the value changes (this is known as long-polling). The multiplex-socket link is for WebSocket connectivity. Versioning is handled using ETags.

What’s nice about LiveResource’s long-polling mechanism is that it is simple and stateless. It’s just a GET request with If-None-Match and Wait headers:

GET /path/to/object HTTP/1.1
Host: example.com
If-None-Match: "b1946ac9"
Wait: 60

There is no complicated socket session emulation. This means you can even use curl:

curl -i -H 'If-None-Match: "b1946ac9"' -H 'Wait: 60' \
    http://example.com/path/to/object

Of course, LiveResource’s WebSocket mechanism can be used for greater network efficiency.

If a resource doesn’t advertise any push capabilities, then the client will resort to plain polling. This means that a LiveResource client is compatible with any resource on the Internet, and automatically becomes more efficient if push capabilities are discovered.

Protocol

See the full spec here.

Test server

There is a test server at test.liveresource.org. You can use it to play around with the protocol or test client code against. For example, there is a resource that reports the current time.

Next Steps

GitHub Repo

Source Site