The APE Protocol

If you are reading this page must likely you are intrigue in learning more of what goes on behind the scene or might be working in some advance modules with custom events dispatched from the server. That being said in this page I'll use a few different terminologies which you might already be familiar with or not and probably only see it in this technical page. I'll explain them anyways.

In this page I'll talk about the protocol or the language that clients and server use to communicate with one another. To explain the process I'll use the terms RAW and CMD. Basically CMD stands for a command and is a request from the client to the server. A RAW is the response of the server for a CMD. Both RAW and CMD:

• Are just json strings
• Have a name and a body, you will notice them when looking at their source in the next few paragraph.

As referred in the official APE documentation a more global terminology that encloses the definition of users and channels objects is pipe. Both users and channels can be refereed as pipes. A user can be refer as a unipipe and a channel as a multipipe. This terminologies might pop here and there but they are not really important as i'll most of the time refer to their simpler terms user and channel.

Taken from the client framework, the following statement:

client.pub("lobby", "Hello World", true);

Will send the following CMD to the server:

[{"cmd":"Event","chl":9,"freq":2,"params":{"event":"message","data":"Hello World","sync":true,"pipe":"d26165a82d34bc8fe37a1bd5deab97fc"},"sessid":"71573850b2bd387570bd46d488b7f25d"}]

In a more structural view it would look like this:

[
	{
		"cmd": 	"Event",
		"chl": 	9,
		"freq": 2,
		"params": {
			"event": 	"message",
			"data":		"Hello World",
			"sync": 	true,
			"pipe":		"d26165a82d34bc8fe37a1bd5deab97fc"
		},
		"sessid": "71573850b2bd387570bd46d488b7f25d"
	}
]

Above, the cmd property is the name of the command, the body of the command is the params property.

Assuming that we are connected to the server and subscribed to the channel lobby, the following should be the response from the server or RAW:

[{"time":"1364508546","raw":"SYNC","data":{"data":"Hello World","event":"message","chanid":"d26165a82d34bc8fe37a1bd5deab97fc","chl":9}}]

In a more structural view it would look like this:

[
	{
		"time":"1364508546",
		"raw":"SYNC",
		"data":{
			"event":	"message",
			"data":		"Hello World",			
			"chanid":	"d26165a82d34bc8fe37a1bd5deab97fc",
			"chl":		9
		}
	}
]

RAW and CMD can be either simpler or more complex than the examples above. For example here is the RAW that other users in the lobby channel would have received:

[{"time":"1364510184","raw":"EVENT","data":{"event":"message","data":"yes","pipe":"d26165a82d34bc8fe37a1bd5deab97fc","from":{"casttype":"uni","pubid":"965298fe6b1a20d5e80042359d212bf2","properties":{"name":"User_Dv0EQ"}},"pipe":{"casttype":"multi","pubid":"d26165a82d34bc8fe37a1bd5deab97fc","properties":{"name":"music"}}}}]

In a more structured view it would look like this:

[
	{
		"time":	"1364510184",
		"raw":	"EVENT",
		"data":{
			"event":	"message",
			"data":		"Hello World",
			"pipe":		"d26165a82d34bc8fe37a1bd5deab97fc",
			"from":{
				"casttype":	"uni",
				"pubid":	"965298fe6b1a20d5e80042359d212bf2",
				"properties":{
					"name": "User_Dv0EQ"
				}
			},
			"pipe":{
				"casttype":	"multi",
				"pubid":	"d26165a82d34bc8fe37a1bd5deab97fc",
				"properties":{
					"name": "lobby"
				}
			}
		}
	}
]

Above, the raw property is the name of the RAW, the data property is body of the RAW. The data.from property is the user/unipipe object of the sender and the data.pipe is the object/pipe from which the RAW was recieved, it could be a user/unipipe or a channel/multipipe. You can tell if a pipe is a multipipe or unipipe by their casttype property.

The framework uses multiple type of CMDs and RAWs internally but you don't have to know what they do just make sure they exists and that should not override them with custom CMDs or RAWs, unless you know what you are doing of course. The chances are that if a RAW or CMD might be important for your application they already have an event bound to them. For example CONNECT is a command and the client connect event is bound to it.

For more information on how to send custom events or commands and listening/handling custom events or RAWs refer to Send Event from the server