From Ape Wiki

APE Protocol Basics

Request to server

APE communicates via HTTP using either the POST or GET methods.

Requests to a server are done on the following URL :

http://[Frequency].[Server URL]/?[JSON-encoded request]

GET example :

GET /?[{"cmd":"CONNECT","chl":0,"params":{"transport":0}}] HTTP/1.1
Host: 0.ape.ape-project.org

POST example :

POST /? HTTP/1.1
Host: 0.ape.ape-project.org
 
[{"cmd":"CONNECT","chl":0,"params":{"transport":0}}]

The digit leading Host header (example: 0.ape.ape-project.org) is the frequency. It is used to detect new sub user. This value increases with each new window/tab that connects to APE and allows for multiple windows/tabs. See Session for more information.

Raw and Command

The APE Protocol works with a system of Raw and Command. Raws and Commands are in JSON format. They are always sent as JSON arrays, each entry of the array is a JSON object representing a raw or a command. Knowing JSON is crucial for understanding RAWs and Commands.

Raw

A raw refers to data sent by the server to the client. A raw is a JSON object with the following mandatory keys:

• raw: Name of the raw
• time: Time of the server when the raw was sent
• data: A JSON object

[
    {
        "raw":"<raw name>",
        "time":"<Send time of the raw>",
        "data":{}
    }
]

Command

A command refers to data sent from the client to the server. A command is a JSON object with the following mandatory keys:

• cmd: Name of the command
• chl: Challenge, the challenge is as integer incremented to every request sent to server.

[
    {
        "cmd":"<command name>",
        "chl":<challenge>
    }
]

TODO : Sessid? Carry return forbidden?

Transport

Use different transport method

TODO

Server side storage

The protocol allows storage of variables on the server side. The client can store key/value pairs on the server. Values stored are kept until the user disconnects or timeouts. For more information see store raw and retreive command.

Handshake

The client initiates a connection negotiation by sending a CONNECT command:

[
    {"cmd":"CONNECT","chl":0,"params":{"transport":0}}
]

For more information see reference of connect command

The server respond with two raws :

[
    {"raw":"LOGIN","time":"1253633967","data":{"sessid":"4622c258248931a7dfb081542eaf589f"}},
    {"raw":"IDENT","time":"1253633967","data":{"user":{"casttype":"uni","pubid":"5288a462f528d3609777f31872d31c8d"}}}
]

For more information see reference of login raw and ident

TODO : Explain sessid? Fix broken links?

Session

Beware! For the below example to work, you need to allow session first on your client side. This is explained on a different page: http://www.ape-project.org/wiki/index.php/Tutorial:Using_sessions

The APE Protocol has a session feature. This feature is used to handle multiple windows/tabs. Each window/tab must use a different url to connect to server. If the server in the http header detects a different host from the same client (client is identified with pubid) it must first send a raw IDENT and CHANNEL (if user are on any channel). Each raw sent by server must be forwarded to other client. This feature is also used to restore the state of an application after a user refreshes the page.

Session Example

Client 0:

POST /? HTTP/1.1
Host: 0.ape.ape-project.org
 
[{"cmd":"CONNECT","chl":0,"params":{"transport":0}}]

Server respond to client 0 :

[
    {"raw":"LOGIN","time":"1253633967","data":{"sessid":"4622c258248931a7dfb081542eaf589f"}},
    {"raw":"IDENT","time":"1253633967","data":{"user":{"casttype":"uni","pubid":"5288a462f528d3609777f31872d31c8d"}}}
]

Client 1 : (User opened a new window/tab)

POST /? HTTP/1.1
Host: 1.ape.ape-project.org
 
[{"cmd":"CHECK","chl":1,"sessid":"4622c258248931a7dfb081542eaf589f"}]

Note that the frequency increased.

Server responds to client 1 :

[
    {"raw":"LOGIN","time":"1253633967","data":{"sessid":"4622c258248931a7dfb081542eaf589f"}},
    {"raw":"IDENT","time":"1253633967","data":{"user":{"casttype":"uni","pubid":"5288a462f528d3609777f31872d31c8d"}}}
]

Client 1 : (User joins a channel)

POST /? HTTP/1.1
Host: 1.ape.ape-project.org
 
[{"cmd":"JOIN","sessid":"4622c258248931a7dfb081542eaf589f","chl":1,"params":{"channels":["testChannel"]}}]

Server responds to client 0 and 1 :

{"raw":"CHANNEL","time":"1253640697","datas":{"pipe":{"properties":{"name":"testChannel"},"casttype":"multi","pubid":"2f50f03539dfe782e233d0a76205b3f3"},
 "users":[{"level":"1","casttype":"uni","pubid":"4622c258248931a7dfb081542eaf589f"}]}}

Note: This one long RAW that has been split into two lines.