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 connection to exchange request and response objects. To invoke a remote method, a request is sent. Unless the request is a notification it must be replied to with a response. Clients are the origin of Request objects. Servers the origin of Response objects.

JSON-RPC is transport agnostic and seeks to simply define the basic object structure and some general principles around usage. It is recommended that guidelines and bes practices be established as a separate documents, as messaging environments may differ even within a single transport like HTTP. This way we can explore and document ways to use JSON-RPC effectively in many environments and even in specialized circumstances.

Compared to existing 1.1 WD and 1.1 ALT specifications, this does not include a version system. This is an intentional fact as hopes are this will become the final specification for the object structure. We should not seek to keep extending the base definition of json-rpc.

1.1 Request Object

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 Object or Array containing the arguments to the method
• id - The request id can be of any type. It is used to match the response object with the request object.

2. Communication Examples

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

• service.echo("Hello JSON-RPC"):

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

• more examples needed here

3. Transports

Previous specifications suggested several environments. However often it implied a bi-directional ability which is difficult in single request http environments. Other documents suggest a traditional client->server setup with one request up and one response down a single http connection. This falls apart when systems like Comet are used and a response object may be coming back out of channel.

This spec defines the client as the origin of a request and the server as the origin of the response. There may be may other nodes in between and the server who accepts the request may not be the one who sends the response. Usually we are talking about one client and one server, perhaps playing both roles with each other. This is why the id property is vital for the client to understand who is saying what, even within a single client->server setup. If you want systems to talk to each other in a bi-directional manner, a double client->server, server<-client setup can be used.

I think it is important that we document which methods implementations expect/allow and encourage writing of code that is flexible. I'll put some diagrams together so we can have further talks over this.

How do people feel about having an object as the param in addition to the traditional array?

How do people feel about defining the practices of each transport in separate documents?