[Interop-dev] Common API

[Nicolás Echániz]

On 10/23/12 13:33, Federico Capoano wrote:
> So, we've been talking about it for quite a while.
> We really need this, we should start working on it actively to make a
> proof of concepts.
> I know many of us (included myself) are developing their own API for
> their nodeDB.
> 
> Let's agree discuss about this common interchange mecchanism.
> 
> I'll start with some thoughts that follow.
> 
> Every community surely has at least NODES in their DB, so I'll start
> with that.
> 
> This is a draft of how my JSON list (and I underline that a list view is
> different from a detail view, a list view is for example
> */api/v1/nodes/* while a detail view would be /api/v1/nodes/<slug>/
> output actually looks like:
> 
> {
> 
>   *
>     meta: {
>       o
>         limit: 1000,
>       o
>         next: null,
>       o
>         offset: 0,
>       o
>         previous: null,
>       o
>         total_count: 1
>     },
>   *
>     objects: [
>       o
>         {
>       o
>           + id: 1,
>           + status: 3, name: "Fusolab Rome",
>           +
>             slug: "fusolab",
>           +
>             description: "Fusolab",
>           +
>             lat: 41.8720419277,
>           +
>             lng: 12.5822391919,
>           + elev: 80,
>           + is_hotspot: true
>         },
> 
> }
> 
> *objects and is_hotspot*
> Pheraphs "objects" should be "nodes" (in this case) and is_hotspot just
> "hotspot". What does hotspot actually means? It means if the node has
> some kind of easy 0 conf access to the network (included internet
> connection), I mean for example an ubiquiti picostation with 2.4 with
> open access. We consider that a useful info here.
> 
> *status*
> Status could be a string, even though a number would make us save some
> bandwidth if we would agree to map numbers to stati, that could be done
> easily in any language.
> 
> *description*
> Description might be left out for the list view and be kept only for the
> detail view to save even more bandwidth.
> 
> *slug*
> Pheraphs not evey node db is going to use a slug but I guess we should
> make it possible to use it and fallback to the ID if not present.
> 
> *meta*
> that is provided out-of-the-box with django-tastypie. It's useful in
> case someone needs to paginate or do some other filtering operations.
> Don't know if it's useful for the interchange mecchanism but that makes
> me wonder, what do you do when you have thousands of nodes?
> 
> *splitting the nodes*
> Is not a good idea to send a huge JSON file to mobile clients. The info
> should be split somehow. I was thinking of splitting data depending on
> zones / groups (nodewatcher calls them projects, CNML calls them zones).
> clients can download data from the zones they're in, so you if you load
> the map of vienna you'll download only the vienna JSON file initially
> and other nearer zones/groups/projects will be loaded in the background
> as you move around. It should really work in a similar way like google
> maps does.
> I think I talked about this with Ralf from Funkfeuer.
> 
> Come on, share your thoughts! I guess if we don't start now we'll never
> do it ;-P

Federico,

This is our current minimal JSON representation of a node.


{
   "network": "quintanalibre.org.ar",
   "zone": "",
   "name": "Tikita"
   "elevation": 490,
   "coords": {
       "lat": "-31.8109526125",
       "lon": "-64.4124984741"
   },
}


A more complete version could look something like this:

{
   "network": "quintanalibre.org.ar",
   "zone": "",
   "name": "Tikita"
   "elevation": 490,
   "coords": {
       "lat": "-31.8109526125",
       "lon": "-64.4124984741"
   },
   "devices": [
       {
           "hostname": "tikita",
           "hardware": "Atheros AR7241 rev 1 / TP-LINK TL-MR3220",
           "software": "OpenWrt r33390",
           "interfaces": [
               {
                   "name": "wlan0"
                   "mac": "92:F6:52:C6:08:AD",
                   "phy": "phy0",
               }
           ]
       }
   ]
}

Two important goals for us regarding the data model are:
* we should be able to translate any network's data to the minimal
representation and then each one should be able to add any additional
data they feel necessary. A general view should still be able to show
minimal data of all nodes in all networks and possibly all links if we
can also decide on a minimal link data model.
* nodes/devices should be able to automatically update all or most part
of their information.


Comparing your model to ours: "hotspot", "description" and "status" are
the important differences. Yours is actually a super-set of ours.


What about the others? do you have a different/contradictory minimal
node data representation in mind or at work?


Cheers,
NicoEchániz