Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
780 lines (497 sloc) 16.6 KB

This section describes all methods in the Web API of Swell.


From your project's html file, import the swell.js script from a Swell server:

<script src="http://localhost:9898/swell.js"></script>

Then, register a callback to get notified when the script was fully loaded so you can start using the API exposed in the service object:

  swell.onReady( (service) => {
    // service = Swell's API entry point


API's entry point

The swell global variable is set in the window object by the swell.js script. However it must be thought as a namespace for the Swell library and not as an entry poiny for the API.

The actual object containing the methods of the API is the one passed to the onReady()'s callback, the service variable in the example. Keep this reference in your code for further use of the API.

The rest of this documentation use the name service to refer to the API's entry point.

You also can get a reference to the entry point calling the global method:

  var service = swell.runtime.get();

Promises and Callbacks

By default, API's methods provide a promise-based syntax:

    .then( user => {  })
    .catch( error => {  });

In case you rather work with callbacks you can get the callback-based entry point of the API with this global method:

  var callbackBasedService = swell.runtime.getCallbackable();

All API methods follow the same syntax for callbacks, for example:

       onSuccess: function(user) {  },
       onError: function(error) {  }  


Swell users are identified by a email-like strings where the domain part is the domain of a Swell server, for example:

All methods expecting an user id will admit just the name part (before the @), assuming she belongs to the current Swell domain.

In federated installations of Swell, is recommended to use full id syntax to avoid issues.


Creates a new user with the provided profile's information.


    id: 'tom',                // no add @domain part
    name: 'Tom Major'         // 
    password: '*****',        //
    email: '', // (Optional)
    locale: 'en_EN',          // (Optional)
    avatarData:               // (Optional) jpg or png in base64 encoded string

.then( profile => {  })
.catch( error => {  });


Edits the profile of the user currently logged in. To delete the value of an attribute, add it to the request with an empty value.

    name: 'Tomas Major '   // change name
.then( profile => {  })
.catch( error => {  });


Retrieves profile information of one single user.


    id: '', // use or nor your swell domain here.               
.then( profile => {  })
.catch( error => {  });


Retrieves profile information of a set of users. The return value is an array of profiles.


    // use or nor your swell domain here. 
    id: ['', '']
.then( arrayOfProfiles => {  })
.catch( error => {  });


Changes user's password having an old password or a temporary recovery token:


    id: 'alice',
    oldPassword: '******',
    newPassword: '******'
.then( result => {  })
.catch( error => {  });

      id: 'alice',
    token: 'AX045KS934SLAN323',
    newPassword: '******'
.then( result => {  })
.catch( error => {  });

The recovery password is obteined calling to recoverPassword()


Sends an email to the given user with a link containing password recovery token.

The user account can be identified with its email address or user id:


    email: '',
    url: 'http://myapp/rememberpassword/$token/$user-id'

.then( result => {  })
.catch( error => {  });



    id: 'alice',
    url: 'http://myapp/rememberpassword/$token/$user-id'

.then( result => {  })
.catch( error => {  });

The server will replace variables $token and $user-id with the actual values.

Your app shoud recognize and accept that URL, retrieve user's id and password token in order to call to password() method.


Majority of API methods require to start an user session with the Swell server.

Swell supports multiple sessions per browser session, it means you can have different open sessions in different tabs of the Web browser and to remember them after browser is closed.


Log a user in the Swell server.

      id : '',
      password : '*****'
    .then( profile => {   });

To log in as anonymous user, don't provide any argument:

    .then( profile => {   });


Lists all sessions opened in the browser. These can be resumed without providing a password again.

    .then( userIdArray => { 


The response is an array of user ids:



Resume an opened session that is still active in the server. On success, returns the user's profile data.

      id : ''
    .then( profile => {  });

If no id parameter is passed, resume the last opened session.

    .then( profile => {  });


Closes the current session with the server and dispose all connections and session data. Optionally accept the user id of the session to be closed.

      id : ''
    .then({  ...  });

Collaborative Objects

Swell allows to store and share data in real-time using collaborative objects. They can be thought as JSON documents with a special syntax and methods to access and change their properties.

A collaborative object has an unique identifier on Internet, for example,

where first part is the domain of the Swell server, and the second part is an id, provided by the client's app or randomly generated by Swell.

When different instances of an app have opened same objects, they can share data in real-time through them.

     App instance #1 (Alice)
 |                             |
 |    Collaborative Object     |
 |                             |<-----> App instance #3 (Chris)
 | |
 |                             |
     App instance #2 (Bob)

Changes in a collaborative object are persisted in the server and transmitted to all instances in real-time.


Load or create a collaborative object openning a live connection with the server.

Creates a new object, set an auto generated id:{})
  .then( object => {


  .catch( error => { ... });

Open or create (if it doesn't exist);{

      id : ""

  }).then( object => {

  .catch( error => { ... });

Object will be created with an autogenerated id, if no id argument is provided. Optionally, a "prefix" can be passed to use in the autogenerated id.

Multiples calls to open() for the same object will return the same single reference.


Closes a collaborative object releasing connection with server and its local resources. Any change or mutation to the object after this call will throw an exception.


      id : ""

  }).then({  })
  .catch( error => { });

Object metadata and live status

In this section we assume we have a collaborative object in the variable object.

There some general properties and methods to control object's metadata:

Id of the collaborative object.


Returns an array of users that can access this object.

object.addParticipant(userId: string)

Shares the object with an user.

object.removeParticipant(userId: string)

Stop sharing the object with an user.

object.setPublic(enable: boolean)

Share/unshare the object with anyone.

object.setStatusHandler(handler: function)

Sets a handler to get notified of metadata events. An example handler follows:

  object.setStatusHandler(function(event) {


      if (event.type == swell.Constants.OBJECT_ERROR) {
        throw event.exception;

      if (event.type == swell.Constants.OBJECT_UPDATE) {
        // information about deltas transmission

      if (event.type == swell.Constants.OBJECT_PARTICIPANT_ADDED ||
          event.type == swell.Constants.OBJECT_PARTICIPANT_REMOVED) {


      if (event.type == swell.Constants.OBJECT_CLOSED) {
          console.log('Object closed.');


Object operations

Now is time to store and share data using a collaborative object. A collaborative object is a kind of special JS object with special syntax to handle real-time sync transparently.

In following examples, we use the var object as the collaborative object returned by the open() method.


Returns a Javascript view of the whole collaborative object.


Returns a Javascript view of part of the collaborative object, according to the provided path.


set(path, value)

Sets or update a property or subpart of the object referenced by a path.

For example, this code adds a new sub object in a property named "20170501-01" of the property "tasks":

    name: 'A new task',
    description: 'bla bla bla',
    estimated_hours: 150

With this syntax, the inserted object will we stored internally as a single piece of data, so you won't be able to listen to specific changes in a particular property, for example, "estimated_hours". It you want to declare sub objects where any property can be listened, you must use a different syntax to make explicit this behaviour:

    name: 'A new task',
    description: 'bla bla bla',
    estimated_hours: 150   


Deletes a propery of the collaborative object. For example:


contains(path, propertyName)

Checks if a property is direct child of the path.

Primitive data types

Collaborative objects supports all basic Javascript basic data types:

object.set('name','JetPad Development Task Board');
object.set('current_sprint', 3);
object.set('active', true);

Arrays / Lists

Collaborative objects support Javascript-like arrays named lists.

Use the set method to create new lists:

object.set('completed_tasks', swell.List.create()); // empty list

  swell.List.create(['20170501-01', '20170501-02'])); // initial values

You can access a list element using a path expression:

object.get('pending_tasks.0'); // returns '20170501-01'

this method is more efficient than getting the whole list as a Javascript array and then accesing index 0:

object.get('pending_tasks')[0]; // returns '20170501-01'

Other list methods are:

push(path, value) / add(value) / addAt(value, index)

Adds a new value at the end of the list or in the specific index.



object.node('pending_tasks').addAt('20170610-02', 2);


Returns and delete the last element of the list.



Returns the element at the index position.


delete(path) / remove(index)

Deletes a element in the list:



length(path) / size()

Returns the length of a list:

object.length('pending_tasks'); // returns 1;


Object nodes and events

Internally, each object's property can be also managed accessing to its "node" object. Use method node() to retrieve it:


Return the node object for the property specified in the path.

object.node('pending_tasks'); // returns a "node" object

Each node has its own node() method, so you can access child nodes:


The main purpose of node objects is to declare listeners for properties in order to react to updates (local or remote):

node.addListener(listenerFunction, [path])

Adds a listener in the node or in a nested node according to the provided path.

  function(event) {

    event.type; // int code.; // the container node.
    event.key; // index or property name updated or removed.
    event.node; // the updated or removed node.

    var propagetEvent = false;
    return propagetEvent;

Possible event types are:


A listener must return a boolean value indicating whether to propagate the event to listeners in ancestor nodes.

node.removeListener(listenerFunction, [path])

Removes a listener previously added.

Friendly names for collaborative objects

Swell provide some utility methods to assign friendly names to collaborative objects:

Assign a name to an object:

      id : '', 
      name : 'The third document' 
    .then(  _names => { ... })    

the result _names is an object with all existing names assigned to the object:

  { "waveId":
        "domain": "",
        "id": "s+a5ce167256"
          "name": "The third document",
          "created": 1507887516893

Query all names of an object by its id:

service.getObjectNames({ id: '' })    .then( _names => { ... });

or to get all synonymous:

service.getObjectNames({ name: 'The third document' })    .then( _names => { ... });

Finally, a name can be removed from an id:

    id : '', 
    name : 'The third document' 
  }).then( _names => { ... });

Participants online/offline status

Applications can track the online/offline status of participants in a collaborative object. First, applications must turn this feature on and register an event handler, always after the object is opened:

	object.setPresenceHandler(function(event) {
    	 console.log( + " is " + event.type);

To signal when the participant is online or offline, use the method setPresence(isOnline:boolean), and to ensure that presence status is set offline when a window is closes , use the window.unload handler:

      window.onunload = function() {

Handling connection status


Set a listener for server connection events.

  function(status, error) {

status can take following values:


An error value means that an unrecoverable error has been detected and your app will need to restart again all Swell resources again.


(Not available yet)

Text documents and Editor

See editor documentation