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 (data sent to the server that does not 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 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.1 Object Specification Object Specification Alternative proposal to 1.1 WD/1.1ALT. 2007-07-30
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 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 intending 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.[1]

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

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

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.[2]

...
--> {"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", "mangoes"],
        1.123
    ]
}

The format of a response might be something like this:

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

Version 2.0

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 Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
  {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}
]

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

Implementations

Name JSON-RPC version Description Language(s)
JsonRpc DNX Router 2.0 A DNX IRouter implementation for Json Rpc v2 requests for Microsoft.AspNet.Routing (frameworks: dnx451, dnxcore50). .NET
JSON-RPC.NET 2.0 A fast, open-source JSON-RPC 2.0 server. Supports sockets, pipes, and HTTP with ASP.NET. Requires Mono or .NET Framework 4.0. .NET
Jayrock 1.0 A server implementation of JSON-RPC 1.0 for versions 1.1 and 2.0 of Microsoft's .NET Framework. .NET
jsonrpc-c 2.0 C library for JSON-RPC on TCP sockets (server only) C
jsonrpc 2.0 Transport-independent JSON-RPC server with parameters validation via jansson C
libjrpc 2.0 Lightweight JSON-RPC 2.0 client and server library C
libjson-rpc-cpp 1.0+2.0 Open source JSON-RPC framework for C++, including client/server support via HTTP and a stub generator for C++ and JavaScript C++
JsonRpc-Cpp 2.0 Open source JSON-RPC implementation in C++ C++
gSOAP 2.0 Open source JSON/JSON-RPC implementation in C/C++, includes code generators for XML/SOAP and JSON/JSONPath C/C++
Phobos 2.0 Implementation for Qt/C++. Abstracts the communication layer (there are TCP and HTTP classes ready to use, also). C++
qjsonrpc 2.0 Implementation for Qt/C++. Supports connection between the messages and QObject's slots (a la QDBus, qxtrpc) and utilizes the new JSON classes included as part of Qt5. C++
cxxtools cxxtools is a generic C++ library for Linux/Unix includes an implementation of jsonrpc client and server which are based on a generic serialization and RPC framework C++
AnyRPC 2.0 Open source RPC framework that support multiple protocols including JSON-RPC C++
jsonrpc-lean 2.0 Lightweight, fast, transport-agnostic, c++11 implementation of the JSON-RPC 2.0 specification C++
clj-bson-rpc 2.0 Full duplex async JSON-RPC 2.0 library upon stream transport (such as TCP and TCP with TLS). Clojure
jsonrpc2-dart 2.0 Implementation for Dart. Server methods are transport-agnostic; Client is HTTP only. Dart
json_rpc_2 2.0 Implementation for Dart. Supports transport-agnostic client, server, and bi-directional communication. Used in the Dart SDK. Dart
Superobject (was JSON Toolkit) 2.0 An implementation for Delphi Delphi
jsonrpc2-erlang 2.0 A minimalistic Erlang implementation that supports concurrent batch requests. Complete, but does nothing besides JSON-RPC 2.0. In particular, JSON encoding and decoding must be performed by the user. Erlang
go/net/rpc ? Standard Go library JSON-RPC implementation Go
Gorilla web toolkit 1.0+2.0 Gorilla is a web toolkit for the Go programming language. Go
json-rpc-server 2.0 An implementation of the server side of JSON RPC 2.0 Haskell
hs-json-rpc 1.0+2.0 А library for writing JSON-RPC client applications in Haskell Haskell
Brutusin-RPC 2.0 Released on 2016. JSON-RPC 2.0 over HTTP and Websockets. Built for maintainability. Easily exposes Java actions as self describing, documented services. Includes builtin service repository and functional testing module Java
corn-gate 2.0 JSON-RPC 2.0/HTPP, REST/HTTP supporting framework that runs on web application servers. POJO, Spring, EJB like objects can be easily exposed. Java
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
JSON Service 2.0 JSON-RPC protocol implementation (server-side) in Java with Service Mapping Description support. It integrates well with Dojo Toolkit and Spring Framework. Java
JSON-RPC 2.0 2.0 A minimalist Java library for parsing, representing and serializing JSON-RPC 2.0 messages (open source). Multiple implementations on the site. (Base, Client, Shell, ...) Java
java-json-rpc 2.0 Implementation for J2EE servers. Java
lib-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
gson-rmi 2.0 Light-weight, transport-independent, extensible RMI framework geared towards distributed computing Java
JDBCWizard 2.0 Generates JSON-RPC 2.0 services for calling PL/SQL and SQL statements in Oracle databases Java
jsonsrv 2.0 A lightweight, JAR-packaged, self-describing, JSON-RPC service framework for JEE (servlet-based) for easily exposing business methods through a JSON over HTTP API. Aimed at creating AJAX/JSON web interfaces Java
jrpc2 2.0 Full featured, modular JSON-RPC 2.0 library with support of batches and named parameters. Server&Client. Features: Express, Koa, Socket.IO middlewares + HTTP, TCP, ZeroMQ transports. JavaScript, Node.js, io.js
jsonrpcjs 1.0(2.0) JavaScript client library for JSON-RPC 1.0, supports call batching has no dependency on external libraries. Main version does not contain support for named parameters, but on the GitHub is pull request version to support JSON-RPC 2.0 (only) JavaScript
Raptor RPC 2.0 A transport-agnostic RPC server with middleware support and an easy-to-use API. JavaScript
easyXDM 2.0 Library for cross-domain messaging with a built-in RPC feature. The library supports all web 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 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
qooxdoo 2.0 Includes a JSON-RPC implementation with optional backends in Java, PHP, Perl and Python. JavaScript, Java, PHP, Perl, and Python
JSON-RPC implementation in JavaScript 2.0 Includes JSON-RPC over HTTP and over TCP/IP sockets JavaScript
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
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
Deimos 1.0+2.0 Server implementation for Node.js/JavaScript. JavaScript
jQuery JsonRpcClient 2.0 JSON-RPC 2.0 client for HTTP and WebSocket backends JavaScript
jrpc 2.0 Transport-agnostic full JSON-RPC 2.0 implementation, bidirectional (client and server on both ends simultaneously), adds backwards-compatible extensions. JavaScript
AFJSONRPCClient 2.0 JSON RPC Client addition to [AFNetworking] 2.0 Objective-C
DeferredKit 1.0 Includes a JSON-RPC 1.0 client. Objective-C
Demiurgic 2.0 JSON-RPC 2.0 client for Objective-C Objective-C
Oxen iPhone Commons JSON components 1.0 JSON-RPC 1.0 client for Objective-C Objective-C
objc-JSONRpc 2.0 An Objective-C JSON-RPC client. Supports notifications, single calls and multicalls Objective-C
JSON::RPC 2.0 JSON-RPC 2.0 server implementation Perl
json-rpc-perl6 2.0 Client and server with dispatch to multi methods, support of positional/named params, notifications, batches and extensible error handling. Perl 6
CSJRPC 2.0 Simple PHP (Server only) implementation of JSON-RPC 2.0. Based on junior PHP
php-json-rpc 2.0 Simple PHP implementation of a JSON-RPC 2.0 over HTTP client. PHP
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
tivoka 1.0+2.0 Universal client/server JSON-RPC library for PHP 5+. 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
JSONRpc2 2.0 Implementation with the "dot magic" for PHP (= support for grouping of methods and separation by dots) PHP
PHP Objective JSON Client 2.0 Objective PHP implementation supports "dot magic" (= support for method grouping 'classes' using dots ) PHP 5.3+
GetResponse jsonRPCClient 2.0 Object-oriented client implementation PHP
zoServices 2.0 PHP, Node.js and JavaScript implementation of JSON-RPC 2.0 PHP, JavaScript, Node.js
json-rpc 2.0 PHP and JavaScript implementation of JSON-RPC 2.0 PHP, JavaScript
jsonrpc-php 2.0 A JSON-RPC client/server implementation in PHP PHP
jsonrpcx-php 2.0 A JSON-RPC client/server implementation in PHP, includes extensions from JSONRPCX PHP
php-json-rpc 2.0 Implementation of JSON-RPC 2.0 excluding events and batches. It provides the implementation of the objects described by the specification and a JSON-RPC client. PHP
php-jsonrpc20 2.0 Transport-independent server implementation PHP
cake-jsonrpc 2.0 CakePHP plug-in providing JSON-RPC server and client. PHP
json-rpc2php 2.0 A easy to use jsonRPC2 server written in PHP with a collection of multiple clients written in PHP, JavaScript, Python and Vala PHP, Python, JavaScript, Vala
jsonrpcinti 2.0 JSON-RPC 2.0 server (PHP) and clients (PHP, JavaScript). PHP, JavaScript
Josser 1.0+2.0 JSON-RPC client for PHP 5.3+ PHP
bsonrpc 2.0 Full duplex JSON-RPC over socket/stream transports, supports Python 2.7, 3.3+, supports gevent. Python
txjason 2.0 A client/server for Twisted. Currently supports netstrings over TCP. Python
Django JSON-RPC 2.0 2.0 A JSON-RPC server for Django Python
Pyjamas A JSON-RPC 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
jsonrpclib 2.0 A JSON-RPC client module for Python. Python
jsonrpclib-pelix 2.0 A fork of the jsonrpclib module, supporting Python 2 and 3. Python
tornadorpc 2.0 Supports serving JSON-RPC; requires the Tornado web server. Python
jsonrpcclient & jsonrpcserver 2.0 A newer standards-compliant client and server pair of modules for Python. Python
tinyrpc 2.0 Supports JSON-RPC over TCP, WSGI, ZeroMQ and others. Separates Dispatching, Protocol and Transports for clean code reuse, i.e. can actually parse JSON-RPC message without running a server. Python
jsonrpc 2.0 An implementation of JSON-RPC 2.0 for Python + Twisted which uses composition to maximize code reusability Python
bjsonrpc 1.0+ Implementation over TCP/IP (asynchronous, bidirectional) Python
json-rpc 1.0+2.0 JSON-RPC transport implementation, supports python2.7, python3.2+. Python
Pulsar JSON-RPC 2.0 Asynchronous JSON-RPC implementation for both server and client, python3.4+. Python
Barrister RPC 2.0 Provides an IDL grammar and JSON-RPC client and server runtime implementations that enforce the IDL Python, Ruby, JavaScript (Node.js + web browser), PHP,
pyramid_rpc 2.0 Flexible JSON-RPC implementation that integrates directly into any Pyramid web application. Works with Pyramid's auth system to provide method-level security and complex method lookup based on method parameters. Python
rjr 2.0 Allows generic JSON-RPC method handlers to be register and invoked over many transport protocols including TCP/UDP, HTTP, WebSockets, AMQP, and more Ruby (EventMachine) server with Ruby and JavaScript clients
jimson 2.0 Client and server for Ruby Ruby
JSON-RPC Objects 1.0+ Pure objects implementation (no client/server) with respect to specifications compliance and API backward compatibility. Ruby
Async JSON-RPC 2.0 client 2.0 Asynchronous (EventMachine) JSON-RPC 2.0 over HTTP client Ruby
play-json-rpc 2.0 A Scala library providing implicit play-json Formats for JSON-RPC 2.0 messages Scala
JSON-RPC RT 2.0 Full support of JSON-RPC 2.0, using TCP as transport protocol Windows Runtime (WinRT)
XINS 2.0 As of version 2.0, supports both JSON and JSON-RPC. XML

The original official homepage[3] has links to more implementations. CPAN lists Perl implementations.

See also

References

  1. ↑ RFC 4627
  2. 1 2 specification - JSON-RPC - Trac
  3. ↑ JSON-RPC - Trac

External links

This article is issued from Wikipedia - version of the Friday, April 22, 2016. The text is available under the Creative Commons Attribution/Share Alike but additional terms may apply for the media files.