Message Frame

A JSON-formatted frame object.

{
    "m": 0,
    "i": 0,
    "n":"function name",
    "o":"payload"
}

Wrap all calls in a JSON-formatted frame object. Responses from the server are similarly wrapped. The API calls are documented as payloads by function name.

KeyValue

m message type

integer. The type of the message. One of: 0 request 1 reply 2 subscribe-to event 3 event 4 unsubscribe-from event 5 error

i sequence number

long integer. The sequence number identifies an individual request or request-and-response pair, to your application. The system requires a non-zero sequence number, but the numbering scheme you use is up to you. No arbitrary sequence numbering scheme is enforced by AlphaPoint. Best Practices: A client-generated API call (of message types 0, 2, and 4) should: Carry an even sequence number Begin at the start of each user session Be unique within each user session. Begin with 2 (as in 2, 4, 6, 8) Message types 1 (reply), 3 (event), and 5 (error) are generated by the server. These messages echo the sequence number of the message to which they respond. See the example, following.

n function name

string. The function name is the name of the function being called or that the server is responding to. The server echoes your call. See the example, following.

o payload

Payload is a JSON-formatted string containing the data being sent with the message. Payload may consist of request parameters (key-value pairs) or response parameters.

Note: You can send the key-value pairs inside the payload in any order. The server controls the order of its response.

Example 1

Example 1

var frame =
{
    "m":0,
    "i":0,
    "n":"function name",
    "o":""
};

var requestPayload =
{
    "parameter1":"value",
    "parameter2":0
};

frame.o = json.Stringify(requestPayload);
// Stringify escapes the payload's quotation marks automatically.
WS.Send(json.Sringify(frame)); // WS.Send escapes the frame

When sending a request in the frame to the software using JavaScript, a call looks like Example 1.

Example 2

Example 2

var frame = json.Parse(wsMessage);

if (frame.m == 1) // message of type reply
{
    //This is a reply
    if (frame.n == "WebAuthenticateUser")
    {
        var LoginReply = json.Parse(frame.o);
        if (loginReply.Authenticated)
        {
            var user = LoginReplay.User;
        }
    }
}

When receiving a frame from the software, use the frame to determine the context, and then unwrap the content, as in Example 2.

Note: If not using JSON Stringify, escape quotation marks.

Last updated

Logo