wiki:specification

Version 4 (modified by daniel.wislocki@…, 12 years ago) (diff)

corrected spelling mistake: muste -> must

JSON-RPC specifications

The specifications should provide the developer with the information needed to implement the protocol.

overview

JSON-RPC is a lightweight remote procedure call protocol. It's designed to be simple!

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 with a response.

1.1 request (method invocation)

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.

1.2 response

When the method invocation completed 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 as an error invoking the method.
  • error - An Error objects 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.

1.3 notification

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

It has the same properties as the request object with one exception.

  • id - Must be null.

2.1 JSON-RPC over stream connections

The specifications do not require a certain transport protocol. The use of TCP/IP socket streams is encouraged. The serialized request and response objects are sent to the peers through the byte streams.

Request and responses may be sent to a peer at any time. The peer must respond to each request unless it is a notification. A response may only be sent in reply to a request.

Closing the connection between peers must raise an exception for all unanswered requests on each peer. A non valid requests or responses must result in closing the connection.

2.2 JSON-RPC over HTTP

With some limitation HTTP requests can be used as a transport for communicating between peers.

A communication between peers, one beeing an HTTP client the other an HTTP server, may span multiple HTTP requests. A client side peer may send one or more requests,notifications or responses its peer by sending an HTTP POST request containing all serialized objects.

The server side peer must reply with responses to all requests sent and may send requests or notifications of it's own. The client side peer must reply to requests received by sending another HTTP POST

To give the serverside peer a chance to send messages the the client side peer the client side peer may reopen communication by sending an empty HTTP POST.

A non valid request must result in closing the connection. A non valid responses must raise an exception for all unanswered requests on the client. Closing a connection must raise an exception for all unanswered requests on the client.

3. JSON Class hinting

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 instanciated using the constructor passing the parameters. Once constructed the properties(propwill be applied.

4. Communication Examples

--> data sent to service
<-- data coming from service

  • service.echo("Hello JSON-RPC")
Error: Failed to load processor javascript
No macro or processor named 'javascript' found
  • multiple request responses

This example shows parts of a communication from an example chat application. The chat service sends notofications for each chat message the client peer should receive. The client peer sends requests to post messages to the chat and expects a positive reply to know the message has been posted.

Error: Failed to load processor javascript
No macro or processor named 'javascript' found