Kiwano API

Documentation

Websocket API version beta2

contact: {joaquin.keller,raluca.diaconu}@orange.com

Overview

In essence, Kiwano infrastructure receives streams of location data from moving objects (users, avatars, bots, drones, ...) and sends back notifications about the neighborhood, updating the list of neighbors with their new positions and states. It also implements communication between moving objects with methods for sending data within neighbors.

While other protocols might be useful, this version of the API only provide an access through websockets. Websockets allow full-duplex connections from browsers and more generally from any program running on a computer with a web access, whether this access is direct or through an http proxy.

Connecting to a Kiwano proxy

The communication with the Kiwano infrastructure is done via a proxy. And, in order to scale, Kiwano spawns as many proxies as needed. To get allocated a proxy, make a call to http://getproxy.hybridearth.net. This will return the websocket url of a proxy with a free slot. And to circumvent cross-domains policies in browsers, getproxy also answers using the jsonp scheme.

The result is returned as a json encoded javascript object with a "url" property providing the websocket url of the allocated Kiwano proxy. Example of returned value:

{url:"ws://188.165.237.23:443"}

When connecting to the websocket the following mandatory parameters have to be provided:

When available, additional optional values can be provided:

Example of connection to Kiwano proxy websocket (in javascript):
ws = New WebSocket("ws://188.165.237.23:443/?iid=7ylqG&lat=48.826944&lng=2.273667&\
                    urlid=http%3A%2F%2Fdb.hybridearth.net%2Fu%2Fanonymous&angle=22.5");

The urlid scheme: providing static data for objects

The urlid is intended to identifies the class of which the object is an instance (i.e. the person behind an avatar, the model of a bot, etc...) but to give an access to the static data.

Messages to Kiwano

Update position and state:

{
    method:"update",    // update position (and other dynamic data)
    urlid:"http://hybridearth.net/u/john.smith",  // this serves as an id
 			   // and as a mean to get more data this class of objects
    iid:"u6nMnT",   // moving object id, an instance of urlid class
                    // format: letters and digits
                    // the combination urlid+iid is unique 
                    // the combination is called moid

	// above urlid and iid fields are not used on websocket version

    notifications:"on",  // optional, values on/off
                   // signal the API to start/stop send notifications
                   // about the neighborhood of this moving object

	real:true,  // 
    lng:52.5,  // the new position
    lat:15.3,
    angle:40, // cardinal direction in degrees, optional
    alt:40, // altitude in meters, optional
    
    appdata:{ // optional application specific dynamic data
    		<appid>: <specific data>, // many or zero fields like this
		
		// example 
    		hybridearth_v0: {
	   		available_for_chat:"yes",
	   		avatar:{
            		// wavefront OBJ format in json
        		}
    		}
    }
}    

Remove a moving object:

{    
	# remove is not used on websocket version
	method:"remove",  # object identified as urlid+iid leaved the system
	urlid:"http://hybridearth.net/u/john.smith", 
	iid:"u6nMnT"   
}

Get all neighbors:

{
	method:"neighbors",  # get all neighbors for urlid+iid
	urlid:"http://hybridearth.net/u/john.smith",
	iid:"u6nMnT"
          # above urlid and iid fields are not used on websocket version
}

Send a message to all neighborhood:


{
    method:"msg2all",
    urlid:"http://hybridearth.net/u/john.smith",
    iid:"u6nMnT",
     # above urlid and iid fields are not used on websocket version
    msg:"Hello you all, nice to meet you",  # utf-8, optional

    appdata:{ # optional application specific data
    		<appid>: <specific data>, # many or zero fields like this
    	  # example 
       funchat: {
	     method:"move_my_avatar",
	     mvnt: {
            # avatar movement description
           }
       }
    }
}

Send a private message to some neighbors:


{
    method:"msg",
    msgid:"DAwqNIcsBUYzUKDT", # optional
    urlid:"http://hybridearth.net/u/john.smith",
    iid:"u6nMnT",
     # above urlid and iid fields are not used on websocket version
    recipients:   # list of recipients
    [
        ("http://hybridearth.net/u/alice.smith","w28QPu"),
    ],
    msg:"Hi Alice, how are you ?",  # utf-8
    
    appdata:{ # optional application specific data
    		<appid>: <specific data>, # many or zero fields like this
	}
}

Notifications from Kiwano

Full list of neighbors for one moving object:

{
    method:"neighbors",
    urlid:"http://hybridearth.net/u/john.smith",
    iid:"u6nMnT",   # whom the neighbors are
     # above urlid and iid fields are not used on websocket version
    nbors:  # list of neighbors
    [
        {
		urlid:"http://hybridearth.net/u/alice.smith",
		iid:"w28QPu",
		lng:52.5,
		lat:15.3,
    		angle:40, # cardinal direction in degrees, optional
		alt:40, # altitude in meters, optional
    		appdata:{ # optional
			<appid>: <specific data>,   # many or zero fields like this
        	}
	   }
    ]
    
}

Notification of changes in the neighborhood:

{
    method:"updates",
    moids:   # list of moving objects concerned by the updates
             # should not be empty
    [
        ["http://hybridearth.net/u/john.smith","u6nMnT"],
    ],
          # above moids field is not used on websocket version

    nbors:  # list of neighbors with updated data
    [
        {
		urlid:"http://hybridearth.net/u/alice.smith",
		iid:"w28QPu",
		lng:52.5,
		lat:15.3,
		angle:40, # cardinal direction in degrees, optional
		alt:40, # altitude in meters, optional
		appdata: {}  # optional
        }
    ]    
}

Notification about moving objects leaving the neighborhood:

{
    method:"removes",
    moids:   # list of moving objects concerned by the removes
             # should not be empty
    [
        ["http://hybridearth.net/u/john.smith","u6nMnT"],
        ["http://hybridearth.net/u/alice.smith","w28QPu"]
    ],

     # above moids field is not used on websocket version

    removes:  # list of objects that are not anymore neighbors of the above
    [
        ["http://hybridearth.net/u/bob.schmidt","YzUKD3"]
    ]
    
}

Reception of a message from a moving object:

{
    method:"msg",
                     # to indicate this is a reply to a specific msg
    from:["http://hybridearth.net/u/john.smith","u6nMnT"]
   
    moids:   # list of moving objects concerned by the message
             # should not be empty
    [
        ["http://hybridearth.net/u/john.smith","u6nMnT"],
        ["http://hybridearth.net/u/alice.smith","w28QPu"#]
    ],   
		# above moids field is not used on websocket version
    msg:"Hi Alice, Hi John, how are you all ?",  # utf-8
    
    appdata:{ # optional
	<appid>: <specific data>,   # many or zero fields like this
	}
}

Serving static data: the urlid scheme

http://hybridearth.net/u/toto?appid=he_js;appid=he_ar 

...work in progress...
{
	name: "Visible Name",
	image:"Picture url",
}
{
    "status": "success",
    "name": "toto",
    "image": "ui/anonymous.png",
    "appdata": {
        "status": "success",
        "he_js": {"color": "undefined", "places": []},
        "he_ar": {}},
    "gender": "male",
    "image": "ui/anonymous.png",
    "userid": "toto",
    "skin": "http://hybridearth.net/models/animated/male/skins/male10.png",
    "mail": "t@t.t",
    "urlid": "http://hybridearth.net/u/toto"
}