API is very simple and consists of three commands. Both request and reply must be in JSON format. Websocket protocol is used.

	{
		"subscribe": "channel_name"
	}
	

	{
		"unsubscribe": "channel_name"
	}
	

	{
		"broadcast": "channel_name"
	}
	

	{
		"broadcast": "channel_name",
		"greeting": "Hello, world!",
		"baz": {
			"foo": "bar"
		}
	}
	

Server will execute above commands silently. No reply will be sent to the given command.

Channel name is any UTF-8 string. Maximum length of the channel name is not limited. But for better performance, the name must be as short as possible.

The want_reply field may be specified if client wants to receive server reply.

	{
		"unsubscribe": "channel_name_2",
		"want_reply": 1
	}
	

In this case server will reply to client with the following:

	{
		"action": "unsubscribe",
		"success": false,
		"channel": "channel_name_2"
	}

Regular HTTP POST protocol may be used for broadcasting. Here is a python example:

	#!/usr/bin/env python3

	from urllib.request import Request, urlopen
	import json

	payload_js = {"broadcast":"test_channel", "foo":"bar", "want_reply":1}
	payload_txt = str.encode(json.dumps(payload_js))
	url = "http://127.0.0.1:21082"
	try:
		request = Request(url, payload_txt)
		res = urlopen(request).read().decode('utf8').strip()
		print(res)
	except BaseException as err:
		print('Exception: ', err)

The above code will form and send to WebPipe server the following HTTP request:

	POST / HTTP/1.1
	Host: 127.0.0.1:21082
	Content-Length: 60

	{"broadcast": "test_channel", "foo": "bar", "want_reply": 1}

Consumer example.
When executed, the code below will connect to the WebPipe server and subscribes to the channel XYZ.

	// address of WebPipe server
	var url = "ws://127.0.0.1:21082";

	// Connect to server
	var sock = new WebSocket(url);

	sock.onopen = function( evt ) {
		var p1 = {
			"subscribe": "XYZ",
			"debug": 1
		};
		// convert JSON object to string
		var js = JSON.stringify( p1 );
		// Subscribe to channel named XYZ
		sock.send( js );
	};

	sock.onmessage = function( evt ) {
		// All the events published to the channel
		// XYZ will be logged to developer console.
		console.log( evt.data );
	};

Publisher example.
When executed, the object p2 will be sent to all subscribers of XYZ channel.

	// Address of WebPipe server
	var url = "ws://127.0.0.1:21082";

	// Connect to server
	var sock = new WebSocket(url);

	sock.onopen = function( evt ) {
		var p2 = {
			"broadcast": "XYZ",
			"foo": {
				"bar": true
			}
		};
		// convert JSON object to string
		var js = JSON.stringify( p2 );
		// Send data to all clients subscribed to XYZ
		sock.send( js );
	};

In control panel you may specify a password for creating new channels.

	{
		"subscribe": "channel_name",
		"password": "secret",
		"want_reply": 1
	}
	

Everything will work as described above if the password is correct. In case of incorrect password, the client will receive the following reply:

	{	"action": "subscribe",
		"success": false,
		"channel": "channel_name",
		"error": "Wrong password"
	}
	

Password is not required in case if channel already exists. The following code will successfuly subscribe to channel if it was created earlier either with or without password:

	{
		"subscribe": "exsisting_channel_name"
	}
	

Right after connection to server, the client receives the following greeting message with private channel name:

	{
		"my_channel": "CLBDIUHED83"
	}
	

Private channel name will not change during the session and will be re-generated when the same client re-connects to server.

Other clients may send direct messages to this specific client using its private channel name.

This is your responsibility to invent the way to broadcast private channel name to other clients :-)

Description   |   Download