JSON-RPC 2.0 Specification Translation Chinese version

JSON-RPC 2.0 Specification

Date of Origin:

2010-03-26 (based on the 2009-05-24 version)

Correction:

2013-01-04

JSON-RPC Working Group <[email protected]>

1 overview

Json-rpc is a stateless, lightweight remote Procedure Call (RPC) protocol. This specification defines several data structures and rules mainly around the way it is handled. This concept can be used to transfer data in the same process, between sockets or HTTP, or in many other messaging environments. It uses JSON (RFC 4627) as the data format.

JSON-RPC's design is simple!

2 conventions

The keywords in this document are "must", "must not", "required", "will", "not", "should", "should not", "recommended", "probable" and "optional" are the same as in RFC 2119.

Because JSON-RPC uses the JSON format, it has the same type of system as JSON (see http://www.json.org or RFC 4627). JSON can represent 4 primitive types (string, numeric, Boolean, and null) and two structured types (objects and arrays). The term "primitive type" represents any of these four original JSON types in this document. The term "structured type" represents a structured JSON type. The first letter of any JSON type in this document is always capitalized: Object, Array, String, number, Boolean, Null. True and false The first letter is also capitalized.

All member names for client and server-side exchanges are case-sensitive. The term functions, methods, and procedures are considered to be exchangeable.

The client is defined as the original request object and the Response object processor.

The server is defined as the original response object and the Request object processor.

The implementation of this specification can easily meet these requirements, even for other different clients or the same client. This specification does not address that level of complexity.

3 compatibility

JSON-RPC 2.0 Request object and Response object may be incompatible with an existing json-rpc1.0 client or server side. However, it is easy to differentiate between two versions because the 2.0 version always contains a member named "Jsonrpc" whose value is the string "2.0" and the 1.0 version does not exist. Most implementations of the 2.0 release should consider handling 1.0 versions of objects, even if they are not peers, and should be given good hints.

4 Request Object

Sends a request object to the server to represent an RPC call. The Request object includes the following members:

Jsonrpc

Specifies the JSON-RPC version of the string, which must be "2.0".

Method

The name of the method called. The method name that begins with RPC represents the methods and extensions inside the RPC and must not be used elsewhere.

Params

It is a structured value that holds the value of a parameter during a method call. The member can be omitted.

Id

An identifier established by the client, which must be a string, numeric, or null value if the member is included in the request. If the member is not included, then it is considered a notification. This value should not generally be null[1] and should not contain the fractional part [2] if it is numeric.

If the client contains an ID member, the server side must contain the same value in the Response object. This member is used to correlate the context between the request and the response between the two objects.

[1] It is not recommended to use NULL as the value of the ID member in the Request object, because this specification uses a null value as a value for an unknown ID. Similarly, because JSON-RPC 1.0 uses an ID value of NULL as a notification, this can cause confusion during processing.

[2] Fractional parts can cause always, because many decimals cannot be accurately represented in binary form.

4.1 Notice

If no ID member is in the Request object, a notification is indicated. The notification Request object indicates that the client is not interested in the corresponding response object and therefore does not need to return the response object to the client. The server must not reply to a notification, even in a bulk request.

Because the response object is not returned, the notification is not easy to define. Therefore, the client will not be aware of any errors (such as: "Invalid Parameters", "Internal error", etc.).

4.2 Structural parameters

RPC calls if there are parameters, you must provide a structured parameter value. Either through the position of an array, or through the name of an object.

By location: The parameter must be an array that contains the values of the order that the server expects.

By name: The parameter must be an object, and the member name of the object matches the parameter name expected by the server. Missing expected parameter names can result in an error. The name must match exactly, including the case of the parameter name expected by the method.

5 Response Object

When an RPC call is initiated, the server must reply to a response, except for the notification. The response is represented as a single object that contains the following members:

Jsonrpc

Specifies the JSON-RPC version of the string, which must be "2.0".

Result

When the call succeeds, the member is required.

If the calling method has an error, the member must not be included.

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

Error

This member is required when an error occurs in the call.

The member must not be included if no error occurred during the call.

The value of this member must be an object defined by Section 5.1.

Id

The member is required.

Its value must be the same as the value of the ID member in the Request object.

If an error occurs when checking the ID in the request object (for example, a conversion error or an invalid request), it must be null.

must contain a result or an error member, but two members must not contain both.

5.1 Error Object

When an RPC call encounters an error, the response object must contain a value of an error member for the object that contains the following members:

Code

A number that represents the type of error that occurred.

This member value must be an integral type.

Message

A string that provides a short description of the error.

The message should be limited to a short sentence.

Data

An original type or structured type value that contains additional information about the error.

This member can be omitted.

The value of the member is defined by the server side (for example, detailed error information, nested error messages, and so on).

The error code value-32768 to-32000 is the reserved value, as a pre-defined error. Any code within this range, but not defined in the table below, is reserved for future use. These error codes are almost identical to the XML-RPC recommendations in the following addresses (http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php).

Code	News	Meaning
-32700	Parsing errors	The server received an invalid JSON. An error occurred in the server parsing JSON text.
-32600	Invalid request	The JSON sent is not a valid request.
-32601	Method not Found	method does not exist or is not visible.
-32602	Invalid parameter	Invalid method parameter.
-32603	Internal Error	JSON-RPC internal error.
-32000 to-32099	Server-side Error	Reserved for specific implementations to define server-side errors.

The application can use the rest of the code to define the error.

6 Bulk Calls

To send multiple request objects at the same time, the client can send an array of request objects.

After all bulk request objects have been processed, the server should use an array as the response, with the corresponding response object in the array. Each request object should correspond to a response object, with the exception of a notification that should not have a response object. The server can concurrently process a bulk RPC call in any order, with parallelism of any width.

Bulk calls can use arrays to return response objects in any order. The client can match between a series of request objects and response objects through the ID members contained in each object.

If the bulk RPC call itself occurs with an invalid JSON or an array that contains at least one value causing the failure, the server-generated response must be a single Response object. If the response array that is sent to the client does not contain a response object, the server must not return an empty array, and should not return anything.

7 Example

Grammar:

--Indicates that data is sent to the server side

<--indicates that data is sent to the client

RPC calls as positional parameters:

RPC Call with positional parameters:

--{"JSONRPC": "2.0", "method": "Subtract", "params": [[[]], "id": 1}
<--{"Jsonrpc": "2.0", "result": +, "id": 1}

--{"JSONRPC": "2.0", "method": "Subtract", "params": [[+], "id": 2}

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

RPC calls as named parameters:

--{"JSONRPC": "2.0", "method": "Subtract", "params": {"subtrahend": $, "minuend": $, "id": 3}

<--{"Jsonrpc": "2.0", "result": +, "id": 3}

--{"JSONRPC": "2.0", "method": "Subtract", "params": {"minuend": $, "subtrahend": +}, "id": 4}

<--{"Jsonrpc": "2.0", "result": +, "id": 4}

Notice:

--{"JSONRPC": "2.0", "Method": "Update", "params": [1,2,3,4,5]}
--{"JSONRPC": "2.0", "Method": "Foobar"}

RPC calls a non-existent method:

--{"JSONRPC": "2.0", "Method": "Foobar", "id": "1"}
<--{"Jsonrpc": "2.0", "error": {"code": -32601, "message": "Method Not Found"}, "id": "1"}

Invalid JSON RPC call

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:

RPC call for invalid request object:

--{"JSONRPC": "2.0", "Method": 1, "params": "Bar"}
<--{"Jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

Invalid JSON for RPC bulk call:

-[

{"JSONRPC": "2.0", "method": "Sum", "params": [1,2,4], "id": "1"},

{"JSONRPC": "2.0", "Method"

]

<--{"Jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse Error"}, "id": null}

RPC call with an empty Array:

--[]

<--{"Jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

Invalid RPC bulk call (non-empty):

--[1]
<--[

{"JSONRPC": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

]

Invalid RPC Bulk call:

-[+]
<--[

{"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 Bulk Call:

-[
{"JSONRPC": "2.0", "method": "Sum", "params": [1,2,4], "id": "1"},
{"JSONRPC": "2.0", "Method": "Notify_hello", "params": [7]},
{"JSONRPC": "2.0", "method": "Subtract", "params": [42,23], "id": "2"},
{"Foo": "Boo"},
{"JSONRPC": "2.0", "Method": "Foo.get", "params": {"name": "Myself"}, "id": "5"},
{"JSONRPC": "2.0", "Method": "Get_data", "id": "9"}
]
<--[
{"JSONRPC": "2.0", "Result": 7, "id": "1"},
{"JSONRPC": "2.0", "result": +, "id": "2"},
{"JSONRPC": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null},
{"JSONRPC": "2.0", "error": {"code": -32601, "message": "Method Not Found"}, "id": "5"},
{"JSONRPC": "2.0", "Result": ["Hello", 5], "id": "9"}
]

RPC Bulk call (all calls are notifications):

-[
{"JSONRPC": "2.0", "Method": "Notify_sum", "params": [1,2,4]},
{"JSONRPC": "2.0", "Method": "Notify_hello", "params": [7]}
]
<--//Bulk Notification Call nothing returns

8 Extensions

The method name of the RPC switch is reserved for system expansion and must not be used anywhere else. Each system extension is defined in the relevant specification. All system extensions are optional.

JSON-RPC 2.0 Specification Translation Chinese version