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