JsonApi

This document describes the JsonApi object in the JavaScript environment for app serivices.

JSON APIs are used on incoming AppWebsocket connections to the app service. JSON APIs are identified by a string identifier. All websocket messages with the "api" attribute matching the identifier are routed to the corresponding JsonApi object.

Table of content

Object JsonApi
Functions onconnected

Object JsonApiConnection
Members domain
sip
dn
guid
app
Functions onmessage
onclose
send
setFlowControl
messageComplete

JsonApi

JsonApi
Constructor for creating and registering a JSON API.

Parameters

string apiThe identifier for the API.
var echoApi = new JsonApi("echo");
onconnected
Registers a callback function that is invoked when a new AppWebsocket is connected that uses the API.

Parameters

function callback(JsonApiConnection conn)The conn parameter passed with the callback can be used to receive and send API messages on the connection.

Return value

JsonApiA reference to the object itself. Useful for method chaining.
new JsonApi("echo").onconnected(function(conn) {
    log("new echo API connection");
});

JsonApiConnection

domain
A string containing the domain of the logged-in user.
sip
A string containing the sip of the logged-in user.
dn
A string containing the display name of the logged-in user. May be undefined.
guid
A string containing the GUID of the logged-in user. May be undefined.
app
A string containing the app the user is authentcated for. For example this attribute can be used to distinguish between connections to user and admin apps.
new JsonApi("echo").onconnected(function(conn) {
    conn.onmessage(function(msg) {
        var obj = JSON.parse(msg);
        if (obj.mt == "Echo") {
            conn.send(JSON.stringify({ api: "echo", mt: "EchoResult", src: obj.src }));
        }
    });
});
onmessage
Registers a callback function that is invoked when receiving an API message

Parameters

function callback(string msg)A string containg a JSON structure. Must be parsed using JSON.parse.

Return value

JsonApiConnectionA reference to the object itself. Useful for method chaining.
new JsonApi("echo").onconnected(function(conn) {
    conn.onmessage(function(msg) {
        var obj = JSON.parse(msg);
        if (obj.mt == "Echo") {
            conn.send(JSON.stringify({ api: "echo", mt: "EchoResult", src: obj.src }));
        }
    });
});
onclose
Registers a callback function that is invoked when the AppWebsocket connection was closed by the client.

Parameters

function callback()The callback that shall be invoked when the connection was closed.

Return value

JsonApiConnectionA reference to the object itself. Useful for method chaining.
new JsonApi("echo").onconnected(function(conn) {
    log("connected");
    conn.onclose(function() {
        log("closed");
    });
});
send
Sends a JSON message.

Parameters

string messageA string containing a JSON structure that represents the API message.

Return value

JsonApiConnectionA reference to the object itself. Useful for method chaining.
conn.send(JSON.stringify({ api: "echo", mt: "EchoResult" }));
setFlowControl
Tells the library that it wants to use flow control. That means that after receiving the onmessage callback, the library should deliver no more messages until the application has called messageComplete

Parameters

bool ontrue if flow control shall be used. false if flow control should not be used.

Return value

JsonApiConnectionA reference to the object itself. Useful for method chaining.
new JsonApi("echo").onconnected(function(conn) {
    conn.setFlowControl(true)
        .onmessage(function(msg) {
            var obj = JSON.parse(msg);
            if (obj.mt == "Echo") {
                conn.send(JSON.stringify({ api: "echo", mt: "EchoResult", src: obj.src }));
            }
            conn.messageComplete();
        });
});
messageComplete
Tells the library that the application is ready to receive the next message using the onmessage callback.

Return value

JsonApiConnectionA reference to the object itself. Useful for method chaining.
new JsonApi("echo").onconnected(function(conn) {
    conn.setFlowControl(true)
        .onmessage(function(msg) {
            var obj = JSON.parse(msg);
            if (obj.mt == "Echo") {
                conn.send(JSON.stringify({ api: "echo", mt: "EchoResult", src: obj.src }));
            }
            conn.messageComplete();
        });
});