Web Service Implementation Scheme 4: Introduction to JSON-RPC

 

Reference: https://en.wikipedia.org/wiki/XML-RPC

 

JSON-RPC is an encoded JSON in the Remote Procedure Call  Protocol . This is a very simple protocol, (very similar to XML-RPC ), defining only a handful of data types and commands. JSON-RPC allows notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server that can be answered out of order.

 

history

Version description outdated

1.0	blueprint	2005
1.1 WD	The working draft adds named parameters, adds specific error codes, and adds introspection.	2006-08-07
1.1 Alt key	A simple JSON-RPC 1.1 replacement is proposed for 1.1 WD.	2007-05-06
1.1 Object Specifications	Object Specification Replacement Proposal 1.1WD/1.1ALT.	2007-07-30
1.2	It is recommended that this document be revised and renamed 2.0.	2007-12-27
2.0	Recommended Specifications	2009-05-24
2.0（Revised-）	specification	2010-03-26

use

JSON-RPC works by sending requests to servers that implement the protocol. In this case, the client is usually a method that the software intends to invoke on the remote system. Multiple input parameters can be passed to a remote method as an array or object, and the method itself can return multiple output data as well. (It depends on the version implemented).

The remote method is to send a request to a remote service by using an HTTP or TCP/IP socket (from version 2.0). When using HTTP, the content type can be defined as 应用/ JSON. ^[1]

A single object of all transport types, serialized using JSON. ^[2] A request is an invocation of a specific method provided by the remote system. It must contain three specific properties:

• 方法 - A string of the name of the method to be called.
• PARAMS - An array of objects is passed as a parameter to the defined method.
• 编号 - The value of any type of response that it is used to match the request it replies to.

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

• 结果 - The data returned by calling the method. This value must be empty if an error occurs when calling the method.
• 错误 - if there is an error in calling the method, otherwise the specified error code 空.
• 编号 - This is the ID of the response request.

As there are notifications that are introduced when no response is required or even expected. Notifications are similar except for the ID, which is not necessary since nothing will return a request. In this case the 的idattribute shall be deleted (version 2.0) or be 空(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", "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}