itc-api v0.1.5

itc-api

A JavaScript client API for the ITC model Server. Works in Node.js and modern browsers.

Installation

npm install itc-api --save

Usage

Creating a new client

// Assuming Node.js or Browser environment with Browserify:
var ITC = require('itc-api');

// Will open a new connection to ws://inthecloud.today:4000 with default options.
var itc = new ITC();

This is shorthand for:-

var itc = new ITC('inthecloud.today', 4000);

To get the open connection or force a re-connection:-

var itc = new ITC();
var connection = itc.connect('inthecloud.today', 4000);

Using the API to Query the ITC Database

The API methods accept a "parameters" map of key/value pairs. The user_id parameter should be passed in to execute the method under the context of the user passed in otherwise it will be run under the context of the "guest" user. The user_id is obtained from the User object returned from the authenticate method.

The client supports two modes:-

• asynchronous
• synchronous

Asynchronous Operations

The general format of the asynchronous methods is:-

itc.asyncfn(parameters, callback);

Parameters are key/value pairs. The last parameter of the asynchronous method accept a callback of the form:-

function(error, results)

For example:-

itc.getDomain({ domain_url: 'inthecloud.today'}, function(error, results) {
    // ....process error and results
});

Methods are executed against a domain under a user context, which is 'guest' by default. The authenticate method is used to change the user's context. For example:-

itc.authenticate({ username: 'someuser', password: 'somepassword', domain_url: 'mydomain.com' }, function(error, results) {
    if (error)
        throw error;
    else if (results.length) {
        user_id = results[0].id;    // to be used in subsequent requests
        console.log('Results: ', results);
    }
});

The /examples directory contains examples of using ITC asynchronous functions.

Synchronous Operations

The asynchronous operations have synchronous equivalents, which contain a "Sync" suffix. The have the same signature except the 'callback' parameter is ommitted and the result is returned by the function. If the method fails an 'error' is thrown.

For example:-

try {
    var user = itc.authenticate({ username: 'someuser', password: 'somepassword', domain_url: 'mydomain.com' });
    var domain = itc.getDomain({ user_id: user.id, domain_url: 'inthecloud.today'});

} finally {

}

The /examples directory contains examples of using ITC synchronous functions.