Skip to content

Json rpc

Json-rpc: http://json-rpc.org/, at the time of writing the 2.0 standard was just becoming real.

In short the standard covers these points :

  • of course it is valid json http://www.json.org, if that's too long for you : json stands for javascript object notation, contains 4 types(string,number,boolean and NULL) and two structured types (arrays and objects) and is a simple readable data format.
  • We talk about clients and servers, and request- and response objects. Clients are originators of requests and receivers of responses, while the servers are the opposite.

request objects

An example :

changetitle
1
2
:::javascript
{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

Request objects (can) have the following members :

  • jsonrpc, always containing "2.0" for version 2.0
  • method, which are strings that may NOT start with a period '.' (internal use)
  • params, an optional json structure (so array or object) containing parameters
  • id, an optional message id, that if present must contain a string or integer number.

Of course the id should match the one in the response object which is expected if id is set.

notification object

An example :

changetitle
1
2
:::javascript
{"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

Id id is not present in the request, it is called a 'notification'. No answer is expected in the form of a response object.

response objects

An example :

changetitle
1
2
:::javascript
{"jsonrpc": "2.0", "result": 19, "id": 1}

The members are :

  • jsonrpc again, again "2.0"
  • result, this is a json structure (object or array), containing the requested data
  • error, an object of a standard form, see next section
  • id, required : same id as the request

either result is filled on success or the error is filled on failure , never both, never none.

error object :

An example within a response :

changetitle
1
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

The error object itself contains the fields :

  • code : a number containing the error code, must be integer number
  • message : a string containing a short (single line) error message
  • data : optional : additional data pertaining the error as any json (number/object/array/string)