Appbase Javascript API


Brief Overview

The Appbase data model is represented as a graph. Vertices are used for storing and retrieving primitive data, and linked to other vertices using edges. Read more about it in the overview document.

Appbase Datatypes

Primitive

  • Boolean
  • Number
  • String

Objects

  • Appbase Reference
    Reference to a vertex on a given Appbase path.
  • Vertex Snapshot

Appbase Object

Appbase is the global object exposed to the Javascript namespace. It has three methods credentials(), create(), ref() and search().


Appbase.credentials() Appbase.credentials(appname, appsecret)

Authorize the app credentials using the name and secret identifiers, as they appear in the developer console.
Returns
boolean true if the app is successfully registered.
Usage

Appbase.credentials(appname, appsecret)

  • name String — App name
  • secret String — App secret key

The base URL of the app is http://*appname*.api1.appbase.io.

Example

var register = Appbase.app('aphrodite', '4d8d0072580912343cd74aa0015cd217');
if (register === true)
  console.log("app successfully registered");

Appbase.create() Appbase.create(namespace, [key])

Create a new Appbase vertex.
Returns
Appbase Reference of the created vertex.
Usage

Appbase.create(namespace, [key])

  • namespace String — A namespace identifier, a new namespace is created if one does not already exist.
  • key (optional) String — Vertex identifier, has to be unique in a namespace. A unique identifier is generated if not provided.

Note key can contain all ascii characters except for whitespaces, `, ~, : or / characters.

Example

var abref = Appbase.create('Materials', 'Ice');

Appbase.ref() Appbase.ref(path)

Reference to an existing vertex from the Appbase URL.
Returns
Appbase Reference of the vertex.
Usage

Appbase.ref(path)

path String Appbase path of the vertex

Example

var abref = Appbase.ref('Materials/Ice/');

An appbase path is very similar to a UNIX path. Here, we are fetching the vertex Ice that we just created under the namespace Materials.


Appbase Reference

Appbase Reference has methods for writing, and reading (listening) on the Appbase graph.


.setData() setData({name: val, ...}, [callback])

Set one or more data properties to this Appbase location.
Usage

abref.setData({name: val, ...}, [callback])

  • {name: val, ...} Javascript object
    • name String — identifier of the data property
    • val Boolean / Number / String — value of the data property
  • callback (optional) Function — will be passed with these as arguments:
    • error String / null – String containing the error message, null if setData() is successfully run.
    • abref Appbase Reference – points to the same path on which the method is called.

Example

/* we will use the 'abref' reference to the vertex at
'Materials/Ice' as used in the example above, and set data on it */
var abref = abref.setData({"color":"A5F2F3", "density": 2.5}, function(error, abref) {
  if (error === null) { // confirming no errors
    console.log(abref)  // should have the properties "color" and "density" set
    // can be used for other things now
  }
});

.removeData() removeData([name1, ...], [callback])

Remove a data property from the current location.
Usage

abref.removeData(property_names, [callback])

  • [name1, ...] Javascript Array — One or more properties to be deleted
    • name1 String – The property identifier
  • callback (optional) Function will be passed with these arguments:
    • error String / null – String containing the error message, null if removeData() is successfully run
    • abref Appbase Reference – of the vertex a the current location.

Example

/* remove the "density" property from our "Ice" vertex */
var abref = abref.removeData(["density"], function(error, abref) {
  if (error === null) { // confirming no errors
    console.log(abref)  // should no longer contain the "density" property
  }
});

.setEdge() setEdge(dest_ref, edgename, [priority], [callback])

Set an edge to a specific destination vertex. It can optionally have a priority.
Usage

abref.setEdge(dest_ref, edgename, [priority], [callback])

  • dest_ref Appbase Reference of the out-vertex

  • edgename String — Identifier for the edge

  • priority (optional) Number — Set a priority for the current edge

  • callback (optional) Function will be passed with these arguments:
    • error String / null – String containing the error message, null if setEdge() is successfully run
    • abref Appbase Reference of the vertex at current location.

Example

abref.setEdge(Appbase.create('Materials/Iron'), 'accessories', function(err, abref) {
  if (typeof err !== String)
    console.log(abref)
});

/* ``abref`` now contains an edge pointing to 'Materials/Iron' */

.removeEdge() removeEdge([name1, ...], [callback])

Removes an outgoing edge from the vertex at the current location.
Usage

abref.removeEdge(name, [callback])

  • [name1, ...] Javascript Array of the properties to be deleted
    • name1 String – Edge name
  • callback Function - will be passed these as arguments:
    • error String / null – String containing the error message, null if removeEdge() is successfully run
    • abref Appbase Reference - points to the same path on which the method is called

.URL() URL()

Appbase URL of the current reference.
Returns
String AppbaseURL
Usage
abref.URL()

This is useful for hyperlinking elements.

Example

var url = abref.URL() // returns "*appname*.api1.appbase.io/Materials/Iron"

.path() path()

Appbase path of the current reference.
Returns
String Appbase path
Usage
abref.path()

Example

var path = abref.path() // returns "Materials/Iron"

.outVertex() outVertex(name)

Reference to the corresponding out vertex with the given name.
Returns
Appbase Reference of the corresponding out vertex
Usage

abref.outVertex(name)

  • name String — Edgename of the out vertex you are looking for.

Example

var abref = Appbase.ref('Materials/Ice');
var outref = abref.outVertex('accesories');

/* `outref` points to the vertex at path: 'Materials/Ice/accesories' */

.inVertex() inVertex()

Reference to the corresponding in vertex from the current vertex.
Returns
Appbase Reference of the in vertex
Usage
abref.inVertex()

Throws an error if abref does not have an in vertex.

Example

var iceref = Appbase.ref('Materials/Ice/accessories');
var abref = iceref.inVertex();

/* `abref` points to the the path 'Materials/Ice' */

var newref = abref.inVertex();   // Throws an error

Data Listeners

on(‘properties’) on(‘properties’, callback)

Listen to value changes on a vertex.
Returns
String The name of the listener, which can be used to turn them off
Usage

abref.on('properties', callback)

  • callback Function — will be passed these as arguments:
    • error String / null – String containing the error message, null if on(‘properties’) listening is successful
    • abref Appbase Reference – points to the path on which the event is fired
    • snapObj Vertex Snapshot – Snapshot of the data stored in the vertex. Take a look at the documentation of Vertex Snapshot

Example

TODO: change according to the method signature
var toolRef = Appbase.ref('https://shawshank.api.appbase.io/prisoner/andy_dufresne/rock_hammer');
// Existing data : {size:12}

toolRef.on('properties',function(err,ref,snap){
   console.log(snap.properties().size);
);

setTimeout(function(){
    toolRef.properties.add('size',13);
},2000);

/* It would immediately log '12' - the existing properties.
 * After 2 secs, It would log '13'.
 */

on(‘edge_added’) on(‘edge_added’, callback)

Get existing edges inserted at a location, and listen to new ones.
Returns
String - the listener’s name and can be used to turn the listener off.
Usage

abref.on('edge_added', callback)

  • callback Function - will be passed these as arguments:
    • error String / null –
    • abref Appbase Reference - pointing to path of the edge
    • [snapObj] Edge Snapshot - Snapshot of the data stored in the vertex, where the edge points. Take a look at the documentation of Vertex Snapshot

snapObj will not be passed if {noData: true} is passed as the options to the listener.

startAt and limit are only effective for retrieving the existing properties. New edges will be returned regardless of their index.

Example


on(‘edge_removed’) on(‘edge_removed’, callback)

Listen to removal of edges.
Returns
String - the listener’s name and can be used to turn the listener off.
Usage

abref.on('edge_removed', callback)

  • callback Function - will be passed these as arguments:
    • error Boolean/String
    • abref Appbase Reference - pointing to path of the edge
    • snapObj Edge Snapshot - Snapshot of the data stored in the vertex, where the edge used to point. Take a look at the documentation of Vertex Snapshot

on(‘edge_changed’) on(‘edge_changed’, callback)

If the properties of the vertex, pointed by an existing edge is changed, this event is fired.
Returns
String - the listener’s name and can be used to turn the listener off.
Usage
abref.on('edge_changed', callback)
  • callback Function - will be passed these as arguments:
    • error Boolean/String
    • abref Appbase Reference - pointing to path of the edge
    • snapObj Edge Snapshot - Snapshot of the data stored in the vertex, where the edge points. Take a look at the documentation of Vertex Snapshot

For this event to fire, in the background the vertexes pointed by all the edges are listened for properties event, and this would be a costly operation in terms of bandwidth if there are a huge number of edges.

Example


off() off([event])

Turn off the listeners on an event.
Returns
Array - containing listeners’ names, which have been turned off.
Usage

abref.off([event])

  • event (optional) String - All the listeners on this event, will be turned off. If no event is given, all the listeners on all the events will be turned off.

Data Snapshots

Data snapshots are immutable copies of the data stored at `Appbase References`_. There are two kinds of snapshots: Property Snapshot and Edge Snapshot, fired when listening to on(‘properties’) or one of the edge listeners.


Property Snapshot

Property Snapshot is an immutable copy of the property data at a location in Appbase. It has the following methods to obtain the changes in the Appbase Reference.

Method Returns
properties() data properties as a Javascript object
prevProperties() data properties before data change as a Javascript object

Edge Snapshot

Edge Snapshot is an immutable copy of the edge data at a location in Appbase. It has the following methods to obtain the edge related changes in the Appbase Reference.

Method Returns
priority() current priority of the edge (null if not set)
prevPriority() previous priority of the edge (null if not set)