JSON-RPC

JSON-RPC is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a handful of data types and commands. In contrast to XML-RPC or SOAP, it allows for bidirectional communication between the service and the client, treating each more like peers and allowing peers to call one another or send notifications to one another. It also allows multiple calls to be sent to a peer which may be answered out of order.

A JSON invocation can be carried on an HTTP request where the content-type is application/json [ [http://www.apps.ietf.org/rfc/rfc4627.html RFC 4627 ] ] . Besides using HTTP for transport, one may use TCP/IP sockets. Using sockets, one can create much more responsive web applications with JSON-RPC, compared to polling data from a service with JSON-RPC over HTTP.

History

Examples

In these examples, --> denotes data sent to a service ("request"), while <-- denotes data coming from a service. (Although this direction often is called "response" in client-server computing, depending on the JSON-RPC version it does not necessarily imply "answer to a request").

Version 1.0

A simple request and response:

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

This example shows parts of a communication from an example chat application. The chat service sends notifications 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. [ [http://json-rpc.org/wiki/specification specification - JSON-RPC - Trac ] ]

...--> {"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}...

Version 1.1 (Working Draft)

The format of the contents of a request might be something like that shown below:

{ "version": "1.1", "method": "confirmFruitPurchase", "id": "194521489", "params": [ [ "apple", "orange", "pear" ] , 1.123 ] }

The format of a response might be something like this:

{ "version": "1.1", "result": "done", "error": null, "id": "194521489"}

Version 2.0 (Specification Proposal)

Procedure Call with positional parameters:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23] , "id": 1}<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42] , "id": 2}<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

Procedure Call with named parameters:

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}<-- {"jsonrpc": "2.0", "result": 19, "id": 4}

Notification:

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

--> {"jsonrpc": "2.0", "method": "foobar"}

Procedure Call of non-existent procedure:

--> {"jsonrpc": "2.0", "method": "foobar", "id": 10}<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": 10}

Procedure Call with invalid JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz"] <-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

Procedure Call with invalid JSON-RPC:

--> [1,2,3] <-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid JSON-RPC."}, "id": null}

Implementations

* Dojo Toolkit offers a broad support for JSON-RPC
* [http://www.progdigy.com/?page_id=6 JSON Toolkit] an implementation for Delphi
* Jayrock is a server implementation of JSON-RPC 1.0 for versions 1.1 and 2.0 of Microsoft's .NET Framework.
* As of version 2.0, XINS supports both JSON and JSON-RPC.
* [http://qooxdoo.org/documentation/0.8/rpc/ JSON-RPC Implementation] in the qooxdoo OO JavaScript application framework, including backends for Java, PHP, and perl.
* Barracuda Web Server's integrated JSON-RPC [http://barracudaserver.com/doc/Lua/JsonRpc.html server] and [http://barracudaserver.com/doc/WebServices/JRpcDoc.html client] online documentation.
* [http://jsolait.net/ JSON-RPC implementation in JavaScript] includes JSON-RPC over HTTP and over TCP/IP Sockets
* [http://code.google.com/p/json-xml-rpc/ JSON/XML-RPC Client and Server Implementations] which abstract-away the differences between JSON-RPC and XML-RPC and permit cross-site requests.
* [http://www.jabsorb.org/ jabsorb] - A lightweight Ajax/Web 2.0 JSON-RPC Java framework that extends the JSON-RPC protocol with additional ORB functionality such as circular references support.
* [http://oss.metaparadigm.com/jsonrpc JSON-RPC implementation in Java] A JavaScript to Java AJAX communications library (now merged with jabsorb.)
* [http://jettison.codehaus.org/ Jettison - Java library]
* [http://homepage.mac.com/andrewlindesay/le/page_lestuff.html LEWOStuff] Includes Java support for JSON-RPC also with specific support for [http://www.apple.com/webobjects WebObjects] .
* [http://search.cpan.org/search?m=all&q=JSON+RPC&n=100 Perl implementations] on the CPAN
* [http://sourceforge.net/projects/jsonrpc-cpp JsonRpc-Cpp] OpenSource JSON-RPC implementation in C++
* [http://tclsoap.sourceforge.net TclSOAP] Includes Tcl support for JSON-RPC in addition to SOAP and XML-RPC.
The official homepage [ [http://json-rpc.org/ JSON-RPC - Trac ] ] has links to [http://json-rpc.org/wiki/implementations more implementations] .

ee also

* Remote procedure call

References

External links

* [http://json-rpc.org/ Official JSON-RPC homepage] includes a Python implementation of JSON-RPC
* [http://groups.google.com/group/json-rpc] "Official" JSON-RPC Google Group