JSON-RPC Specifications (decoupled objects)
****************
A working progress from Matthew P. C. Morley (MPCM) based on the original spec.
****************
The specifications should provide the developer with the information needed to implement the messaging format. Topics related transport environments and service descriptions should be covered in supporting specifications (many these have not yet been written).
NOTE: A JSON-RPC 1.1 Working Draft and a 1.1 ALT specification has been published, then opened for review and comments. This specification is an attempt to introduce minor feature change as it relates to the original 1.0 spec, provide a clear stance that json-rpc is not tied to a transport. It does not address the major topics in the other 1.1 specs.
The modifications to the original spec include extending the params property in the Request object to be able to be an object and removal of any transport specific requirements.
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 best 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:
1.2 Response Object
When the method invocation completes, the service must reply with a response. The response is a single object serialized using JSON.
It has three properties:
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.
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?