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. JSON-RPC allows for notifications (info sent to the server that doesn't require a response) and for multiple calls to be sent to the server which may be answered out of order.

History

Version	Description	Dated
1.0	Original version Currently considered official according to	2005
1.1 WD	Working draft Adds named parameters, adds specific error codes, and adds introspection functions.	2006-08-07
1.1 Alt	Suggestion for a simple JSON-RPC 1.1 Alternative proposal to 1.1 WD.	2007-05-06
1.2	Proposal A later revision of this document was renamed to 2.0.	2007-12-27
2.0	Specification proposal	2009-05-24
2.0 (Revised)	Specification proposal	2010-03-26

Usage

JSON-RPC works by sending a request to a server implementing this protocol. The client in that case is typically software wanting to call a single method of a remote system. Multiple input parameters can be passed to the remote method as an array or object, whereas the method itself can return multiple output data as well. (This depends on the implemented version.)
A remote method is invoked by sending a request to a remote service using HTTP or a TCP/IP socket (starting with version 2.0). When Using HTTP, the content-type may be defined as application/json.

All transfer types are single objects, serialized using JSON. A request is a call to a specific method provided by a remote system. It must contain three certain properties:

• method - A String with the name of the method to be invoked.
• params - An Array of objects to be passed as parameters to the defined method.
• id - A value of any type, which is used to match the response with the request that it is replying to.

The receiver of the request must reply with a valid response to all received requests. A response must contain the properties mentioned below.

• result - The data returned by the invoked method. If an error occurred while invoking the method, this value must be null.
• error - A specified Error code if there was an error invoking the method, otherwise null.
• id - The id of the request it is responding to.

Since there are situations where no response is needed or even desired, notifications were introduced. A notification is similar to a request except for the id, which is not needed because no response will be returned. In this case the id property should be omitted (Version 2.0) or be null (Version 1.0).

Examples

In these examples, --> denotes data sent to a service (request), while <-- denotes data coming from a service. (Although <-- 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.

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

Because params field is an array of objects, the following format is also ok:

{
 "method": "methodnamehere",
 "params": [
            {
             "firstparam": "this contains information of the firstparam.",
             "secondparam": 1121211234,
             "thirdparam": "this contains information of the thirdparam."
            },
            {
             "fourthparam": "this is already a different object.",
             "secondparam": "there can be same name fields in different objects.",
             "thirdparam": "this contains information of the thirdparam."
            }
           ],
 "id": 1234
}

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

Name	JSON-RPC Ver.	Description	Language(s)
jsonrpcjs	2.0	Javascript client library for JSON-RPC 2.0, supports call batching has no dependency on external libraries.	JavaScript
jsonrpc4j	2.0	Java implementation JSON-RPC 2.0 supporting streaming as well as HTTP servers. It also has support for spring service exporter\consumer.	Java
json-rpc	1.0	Generic java/javascript implementation which integrates well on Android/Servlets/Standalone Java/Javascript/App-Engine applications.	Java / JavaScript
php-json-rpc	2.0	Simple PHP implementation of JSON-RPC 2.0.	PHP
easyXDM	2.0	Library for cross-domain messaging with a built in RPC feature. The library supports all browsers by using a mix of postMessage, nix, frameElement, window.name, and FIM, and is very easy to use.	JavaScript
Dojo Toolkit	1.0+	offers a broad support for JSON-RPC	JavaScript
Pmrpc	2.0	is an inter-window and Web Worker remote procedure call JavaScript library for use within HTML5 browsers. Pmrpc is an implementation of JSON-RPC using the HTML5 postMessage API for message transport.	JavaScript
JSON Toolkit	2.0	an implementation for Delphi	Delphi
JSON-RPC.Net	2.0	An open-source JSON-RPC 2.0 server built with C# for ASP.NET and JSON.NET.	.NET
Jayrock	1.0	is a server implementation of JSON-RPC 1.0 for versions 1.1 and 2.0 of Microsoft's .NET Framework.	.NET
XINS	2.0	As of Version 2.0, supports both JSON and JSON-RPC.	XML
qooxdoo	2.0	includes a JSON-RPC implementation with optional backends in Java, PHP, Perl and Python.	JavaScript, Java, PHP, PERL, & Python
JSON-RPC online documentation	2.0	Barracuda Web Server's integrated	LUA
JSON-RPC implementation in JavaScript	2.0	includes JSON-RPC over HTTP and over TCP/IP Sockets	JavaScript
JSON/XML-RPC Client and Server Implementations	1.1	Abstract-away the differences between JSON-RPC and XML-RPC and permit cross-site requests.	PHP
jpoxy	2.0	A simple Java JSON-RPC implementation designed to be simple to implement and able to expose public methods in existing POJOs via a robust RPC framework.	Java
jabsorb	2.0	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.	JavaScript, Java
Jettison		Collection of Java APIs (like STaX and DOM) which read and write JSON	Java
JSON Service	2.0	Another JSON-RPC library for Java build on top of Jackson library.	Java
Perl implementations	2.0	find it on the CPAN	Perl
json-rpc-perl6	2.0	Client and server with dispatch to multi methods, support of positional and named params and extensible error handling.	Perl 6
JsonRpc-Cpp	2.0	OpenSource JSON-RPC implementation in C++	C++
TclSOAP	2.0	Includes Tcl support for JSON-RPC in addition to SOAP and XML-RPC.	TCL
Pyjamas		A JSONRPC client implementation, as standard (Pyjamas is a framework where applications are written in Python but are compiled to Javascript).	Python
Zope 3	1.1	Python based JSON RPC server and client implementation for Zope 3	Python
JQuery JSON-RPC Server	2.0	This is a JSON-RPC server, specifically made to work with the Zend Framework JSON RPC Server. The Zend Framework JSON-RPC server is mildly off spec, and therefore this may not work with other JSON-RPC servers.	PHP, JavaScript
jsonrpc2php	2.0	A PHP5 BSD'd JSON-RPC 2.0 Core class and example Server	PHP
jsonrpclib	2.0	A JSON-RPC client module for Python.	Python
tornadorpc	2.0	supports serving JSON-RPC requires the Tornado web server.	Python
JSON-RPC 2.0	2.0	is a minimalist Java library for parsing, representing and serializing JSON-RPC 2.0 messages (open source). Multiple Implementaions on the site. (Base, Client, Shell, ...)	Java
Synopse		Open Source Delphi database access, User Interface generation, reporting, i18n in Client/Server AJAX/RESTful model.	Delphi
DeferredKit	1.0	includes a JSON-RPC 1.0 client.	Objective-C
java-json-rpc	2.0	JSON-RPC 2.0 implementation for J2EE servers.	Java
lib-json-rpc	2.0	JSON-RPC 2.0 implementation on servlet, client, javascript	Java
simplejsonrpc	2.0	Another simple JSON-RPC 2.0 Servlet, servicing the methods of a class.	Java
Tivoka	2.0	An object oriented JSON-RPC 2.0 client and server implementation for PHP	PHP
junior	2.0	client/server library for JSON-RPC 2.0	PHP
json-rpc-php	2.0	client/server library for JSON-RPC 2.0	PHP
jimson	2.0	JSON-RPC 2.0 client and server for Ruby	Ruby
The Wakanda platform	2.0	includes a JSON-RPC 2.0 client in its Ajax Framework and a JSON-RPC 2.0 service in Server-Side JavaScript	JavaScript ?
Phobos	2.0	A JSON-RPC 2.0 implementation for Qt/C++. You can use it to send and receive messages over any communication layer (there are TCP and HTTP classes ready to use, also).	C++
Deimos	1.0+	is a JSON-RPC 1.0 and 2.0 implementation for nodejs/javascript (server-side).	JavaScript
JSONRpc2	2.0	Another PHP implementation of 2.0 protocol with the "dot magic" for php (= support for grouping of methods and separation by dots)	PHP
jsonrpc	2.0	An implementation of JSON-RPC 2.0 for Python + Twisted which uses composition to maximize code reusability	Python
Demiurgic	2.0	JSON-RPC 2.0 Client for Objective-C	Objective-C
GetResponse jsonRPCClient	2.0	An object oriented JSON-RPC 2.0 client implementation for PHP	PHP
RJR	2.0	Ruby Json Rpc Library - serve and consume json-rcp requests over amqp, websockets, http, and more	Ruby

The original official homepage has links to more implementations.

See also

• Remote procedure call
• SOAPjr - a hybrid of SOAP and JSON-RPC
• JSON-WSP - a JSON-RPC inspired protocol with a service description specification.

External links

• Official JSON-RPC homepage includes a Python implementation of JSON-RPC
• JSON-RPC Google Group discussing topics of and around the protocol