API Usage - NickGerleman/Nimbus_Webapp GitHub Wiki

General Information

All API requests must be done using HTTPS (including those involving websockets/Faye)

All API requests must be done using the api subdomain except for requests to /socket (although it is still recommended to use the api subdomain)

an example of these rules is as follows

bad: http://nimbuu.us/user/info
good: https://nimbuu.us/api/user/info

Identity of the user is ascertained by the use of built in session cookies for the purpose of simplicity. Other methods may be added in the future. Nonew of these currently accept any paramters.

API Commands

GET /user

Returns all of the information pertaining to a user

{
  “name”:“John Doe”,
  “id”:46,
  “socket_token”:“some hex encoded string”,
  “connection_ids”:[287]
}

GET /user/connections

Returns all of the connections belonging to a user a user

[
  “{
    “name”:“Connection 1”,
    “id”:287,
    “type”:“dropbox”,
    “access_token”:“another random string”,
    “last_updated”:“2013-07-24T07:24:04-05:00”
    "state":"success"
  }
]

GET /connection/id

Returns the connection with the specified id

{
  “name”:“Connection 1”,
  “id”:287,
  “type”:“dropbox”,
  “access_token”:“another random string”,
  “last_updated”:“2013-07-24T07:24:04-05:00”
  "state":"success"
}

Socket Information

A socket is used in order to update clients about things such as updated connections. Clients may also publish information to other clients, but not the server.

Socket connections are done using Faye The Faye client can be downloaded from /api/socket/client.js The Faye mountpoint is simply /socket

Faye channels are simply the user’s id value, where the token is an HMAC generated digest of the id. Due to the nature of this scheme, the channel and token will never change, meaning it can be cached.

Setting the token is done using Faye extensions as seen here Specifically, to use it you must add an extension that adds an auth_token to all outgoing messages

The simplest way to do that would be something similar to:

client.addExtension({
  outgoing: function(message, callback) {
    message.ext = message.ext || {};
    message.ext.auth_token = 'some string';
    callback(message);
  }
});

All messages must be a JSON object with a property of message_type that dictates the type of the message and message_content which is the message itself.

The following types are valid:

• “connection_update”
• “connection_remove”
• “client_message”

More may be added in the future

 ##Socket Messages

###connection_update

Used to either add a connection, or to update an existing one

{
  “message_type”:“connection_update”,
  “message_content”:{
    “id”:287,
    “name”:“Connection 1”,
    “type”:“dropbox”,
    “access_token”:“another random string”,
    “last_updated”:“2013-07-24T07:24:04-05:00”
  }
}

###connection_remove

Used when a connection is removed

{
  “message_type”:“connection_remove”,
  “message_content”:{
    “id”:287
  }
}

###client_message

client_message is used exclusively for messages coming from the client and contain an information about the state of the client rather than the user. An example would be a client wanting to update other clients that it has detected that a file has changed, or that a check for new files has occured. Doing this allows for faster checks of file updates.