JSON RPC

Overview

JSON-RPC is a stateless, light-weight remote procedure call(RPC) protocol.

Primarily this specification defines several data structure and the rules around their processing.

It is transport agnostic in that the concepts can be within the same process, over sockets, over http, or in many various message passing environment.

It uses JSON(RFC 4627) as data format.

Request Object , a rpc call is represented by sending a Request Object to a Server. The Request Object has the following members

jsonrpc: A String specifying the version of the JSON-RPC protocol, MUST be exactly "2.0"

method: A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else

params: A Structured value that holds the parameter valeus to be used during the invocation of the method. This member MAY be omitted.

id, An identifier established by the Client that MUST contain a String, or NULL value if included.

If it is not included, it is assumed to be a notification. The value SHOULD normally not be NULL and Number SHOULD NOT contains fractional part.

The server MUST reply with the same value in Response object if included. This member is used to correlate the context between the two object.

Notification

A Notification is a Request Object without an id member.

A Request Object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response Object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Parameter Structure

If present, parameters for the rpc call MUST be provided as Structured Value. Either by-position through an Array or by-name through an Object.

Response Object: when a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications. The Response is expressed as a single JSON Object, with the following members.

jsonrpc

result

The member is REQUIRED on success

The member MUST NOT exist if there was an error invoking the method

The value of this member is determined by the method invoked on the server

error

This member is REQUIRED on error

This member MUST NOT exist if there was no error triggered during invitation

The value for this member MUST be an Object

A string specifying the version of the JSON-RPC protocol, MUST be exactly "2.0"

Error Object

code

A Number that indicates the error type that occurs

This MUST be an integer

message

A String providing a short description of the error

The message SHOULD be limited to a concise single sentence

data

A Primitive or Structured value that contains additional information about the error

This may be omitted

The value of this member id defined by Server

Batch

To send several Request objects at the same time, the Client MAY send an Array filled with Request Object.

The server should respond with an array containing the corresponding Response Objects, after all of the batch Response Objects for processed. A Response object SHOULD exist for each Request Object, except that there SHOULD NOT be any Response Objects for Notifications. The Server MAY process a batch rpc call as a set of concurrent tasks, processing them in any order and with any width of parallism.

The Response objects being returned from a batch call MAY be returned in any order within the Array. The Client SHOULD match contexts between the set of Request objects and the resulting set of Response Objects based on the id member within each Object.

If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response Object. If there are no Response Objects contained within the Response Array as it is to be sent to the client, the server MUST NOT return an empy Array and should return nothing at all.

Examples

Syntax

--> data sent to Server

<-- data sent to Client

rpc call with positional parameters

--> {"jsonrpc": "2.0", "method": "substract", "params": [42, 23], "id": 1}

<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

--> {"jsonrpc": "2.0", "method": "substract", "params": [23, 42], "id": 2}

<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

rpc call with named parameters

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

<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

a Notification

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

rpc call of non-existent method

--> {"jsonrpc": "2.0", "method": "foobar", "id": 1}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}

rpc call with invalid JSON

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

rpc call with invalid Request Object

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

rpc call Batch, invalid JSON

--> [
{"jsonrpc": "2.0", "method": "sum", "params": [1,2,3], "id": 1},
{"jsonrpc": "2.0", "method"
]
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

rpc call with an empty Array

--> []
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

rpc call with an invalid Batch(but not empty)

--> [1]
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

rpc call with invalid Batch

--> [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},
]

rpc call Batch

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

<-- [
  {"jsonrpc": "2.0", "result": 7, "id": 1},
  {"jsonrpc": "2.0", "result": 7, "id": 2},
  {"jsonrpc": "2.0", "result": 7, "id": 3},
]

rpc call Batch(all Notifications)

--> [
  {"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,3] },
  {"jsonrpc": "2.0", "method": "notify_hello", "params": [6] }
]

<-- // Nothing is returned for all notification batches