Skip to content
This repository has been archived by the owner on Apr 13, 2022. It is now read-only.

Latest commit



141 lines (106 loc) · 3.6 KB

File metadata and controls

141 lines (106 loc) · 3.6 KB

Solid WebSockets API Spec

Note: This spec is a component of the parent Solid specification; the parent spec and all its components are versioned as a whole.


This is a draft protocol. This specific version is identified by the string solid-0.1.

WARNING: Future versions of this protocol will NOT be backward compatible for security reasons.

Protocol description

Live updates are currently only supported through WebSockets. This describes a subscription mechanism through which clients can be notified in real time of changes affecting a given resource.


The PubSub system is very basic. First, a client needs to obtain the URI of the WebSocket. The WebSocket server URI is the same for any resource located on a given data space (same hostname). To discover the URI of the WebSocket server, clients can send an HTTP OPTIONS request. The server will then include an Updates-Via header in the response:


OPTIONS /data/test HTTP/1.1


HTTP/1.1 200 OK
Updates-Via: wss://


Then, the client needs to open a WebSocket connection to that URI. The client SHOULD include the protocol version solid-0.1 in the Sec-WebSocket-Protocol header.

For example, in JavaScript, this could be done as follows:

const socket = new WebSocket('wss://', ['solid-0.1']);

Upon connection, the server SHOULD indicate the protocol version as follows:

protocol solid-0.1

If the client did not specify a Sec-WebSocket-Protocol header, the server SHOULD warn the client as follows:

warning Missing Sec-WebSocket-Protocol header, expected value 'solid-0.1'

Otherwise, if the set of values obtained from parsing the Sec-WebSocket-Protocol header does not contain solid-0.1, then the server SHOULD emit a warning and SHOULD close the connection:

error Client does not support protocol solid-0.1


Then, the client needs to sub(scribe) to a given resource URI. If any change occurs in that resource, a pub(lish) event will be sent to all the subscribed clients.

To subscribe to a resource, clients will need to send the keyword sub followed by an empty space and then the URI of the resource:


If a change occurs and the client is subscribed to that resource, it will receive a WebSocket message composed of the keyword pub, followed by an empty space and the URI of the resource that has changed:


Only absolute URIs should be used in both the sub and the pub message.

Subscribing to a container can also be really useful, since all CRUD operations (POST, PUT, PATCH, DELETE) performed on resources of that container will trigger a notification for the container URI. This makes synchronization between multiple apps really easy.

For example, a client subscribes to the data/ container:


If another client deletes the resource foo inside data/:


DELETE /data/foo HTTP/1.1

Then the following notification message will be sent:



Here is a Javascript example on how to subscribe to live updates for a test resource at

var socket = new WebSocket('wss://', ['solid-0.1']);
socket.onopen = function() {
socket.onmessage = function(msg) {
	if ( &&, 3) === 'pub') {
        // resource updated, refetch resource