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 info unlicensed
Functions	onmessage onclose send setFlowControl messageComplete encrypt decrypt hash

JsonApi

Constructor for creating and registering a JSON API.

Parameters

string api

The 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

JsonApi

A 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.

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.

info

A string containing the login info of the user. It contains a JSON structure that includes additional info like the PBX of the user.

unlicensed

A boolean that tells whether the logged-in user got a license for the related app.

new JsonApi("echo").onconnected(function(conn) {
    log("connected user=" + conn.sip + "@" + conn.domain + (conn.unlicensed ? " (unlicensed)" : " (got app license)"));
});

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

JsonApiConnection

A 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

JsonApiConnection

A reference to the object itself. Useful for method chaining.

new JsonApi("echo").onconnected(function(conn) {
    log("connected");
    conn.onclose(function() {
        log("closed");
        conn = null;
    });
});

send

Sends a JSON message.

Parameters

string message

A string (max. length 65535) containing a JSON structure that represents the API message.

Return value

JsonApiConnection

A 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 on

true if flow control shall be used. false if flow control should not be used.

Return value

JsonApiConnection

A 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

JsonApiConnection

A 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();
        });
});

encrypt

Encrypts a string using the shared secret of the connection and a random seed.

Parameters

string seed	A seed value that shall be unique for each call. The seed is needed by the remote party for decryption.
string data	The string to be encrypted.

Return value

string

The encrypted string.

var seed = "some seed";
var secret = "some secret text";
var encryptedText = conn.encrypt(seed, secret);
conn.send(JSON.stringify({ mt: "SomeMessage", seed: seed, encryptedText: encryptedText }));

decrypt

Decrypts a string using the shared secret of the connection and a random seed.

Parameters

string seed	The seed needs to be given by the remote party for decryption.
string data	The encrypted string.

Return value

string

The decrypted string.

conn.onmessage(function(msg) {
    var obj = JSON.parse(msg);
    if (obj.mt == "SomeMessage") {
        var secret = conn.decrypt(obj.seed, obj.encryptedText);
    }
});

hash

Calculates a hash value using the shared secret of the connection and a random seed.

Parameters

string seed	A seed value that shall be unique for each call.
string data	The string to be hashed.

Return value

string

The calculated hash value.

var seed = "some seed";
var text = "some secret text";
var hash = conn.hash(seed, secret);
conn.send(JSON.stringify({ mt: "SomeMessage", text: text, seed: seed, hash, hash }));