Technology Overview

JavaScript Object Notation – Remote Procedure Call or JSON-RPC defines a handful of data types and commands. The general mechanism consists of two peers establishing a data connection. During the lifetime of a connection, peers may invoke methods provided by the other peer. To invoke a remote method, a request is sent. Unless the request is a notification it must be replied to with a response.

Request

A remote method is invoked by sending a request to a remote service. The request is a single object serialized using JSON.

It has three properties:

• method – A String containing the name of the method to be invoked.
• params – An Array of objects to pass as arguments to the method.
• id – The request id. This can be of any type. It is used to match the response with the request that it is replying to.

Response

When the invocation method completes, the service must reply with a response. The response is a single object serialized using JSON.

It has three properties:

• result – The Object that was returned by the invoked method. This must be null in case there was an error invoking the method.
• error – An Error object if there was an error invoking the method. It must be null if there was no error.
• id – This must be the same id as the request it is responding to.

Notification

A notification is a special request which does not have a response. It is a single object serialized using JSON.

The notification has the same properties as the request object with one exception – the id must be null.

JSON-RPC Data Types

There are only simple data types defined in JSON. To overcome this problem in a JSON compatible way a special property for objects is introduced – {"__jsonclass__":["constructor", [param1,...]], "prop1": ...} The object is then instantiated using the constructor, passing in the parameters. Once constructed, the (prop1, ...) properties will be applied.

Examples

• service echo ("Hello JSON-RPC")

  --> { "method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
  <-- { "result": "Hello JSON-RPC", "error": null, "id": 1}

• multiple request responses

  --> {"method": "postMessage", "params": ["Hello all!"], "id": 99}
  <-- {"result": 1, "error": null, "id": 99}
  <-- {"method": "handleMessage", "params": ["user1", "we were just talking"], "id": null}
  <-- {"method": "handleMessage", "params": ["user3", "sorry, gotta go now, ttyl"], "id": null}
  --> {"method": "postMessage", "params": ["I have a question:"], "id": 101}
  <-- {"method": "userLeft", "params": ["user3"], "id": null}
  <-- {"result": 1, "error": null, "id": 101}