[Sugar-devel] sugar-web: documenting the API

[Manuel Quiñones]

Hi, this is an attemp to formalize and document the communication
between web activities and the shell, to push the development of Sugar
on Android.

I'm proposing JSON-RPC 2.0 as a format.  Specification:
http://www.jsonrpc.org/specification

In general the Sugar Shell acts as the server and the Sugar web
activity acts as the client.  But we also have communication the other
way round.

Note that is transport agnostic: Sugar GTK uses websockets, but Sugar
Android can use another message passing environment (in the same
process, HTTP, etc).

Here is the draft I have now:
http://markable.in/file/fe27c384-1a38-11e3-b539-984be164924a/

This doc will probably live in sugar-web/bus.js .

If everyone agrees, I will be changing the current code to make it
JSON-RPC compliant.  Below is the documentation of request, response
and error object in the context of Sugar (also could live in
sugar-docs).

Request object. Is a JSON with the following members:

- method: String with the name of the method invoked
- params: a structured value, JSON Object {} or Array []
- id: String, Number or Null
- jsonrpc: the String "2.0"

The server must send a response object.

We are already using this format (almost.. the only element we miss is
the jsonrpc member, but I have sent a PR that fixes this).

As a simple organization of methods, we use a dot notation in the
name.  for example: "activity.get_xo_color".  We currently have
modules "activity" and "datastore".

For 'params' we are using Arrays in all the current requests.  this
means that we are passing parameters by position, not by name.

For 'id' we are using integers.

Notification object. Is like a request but without an 'id' member.
Unlike the requests, the server must not send a response.

Response object. Is a JSON with the following members:

- result: Object
- error: Object (see below)
- id: String, Number or Null
- jsonrpc: the String "2.0"

Result and error are mutually exclusive.

Error object.  Is a JSON with the following members:

- code: Integer
- message: String
- data: optional, a primitive or structured value

Error codes from and including -32768 to -32000 are reserved for
pre-defined errors.


-- 
.. manuq ..