Content deleted Content added
No edit summary |
gr. |
||
| (46 intermediate revisions by 30 users not shown) | |||
Line 1:
{{Short description|JSON-based wire protocol for remote procedure calls}}
'''JSON-RPC''' ('''JavaScript Object Notation-Remote Procedure Call''') is a [[
The JSON-RPC protocol is transport-independent and can be carried over many different data transport protocols, including [[file descriptor]] I/O, [[HTTP]] and [[TCP]]. It does not directly provide any support for authentication or authorization.
== History ==
Line 9 ⟶ 12:
|-
| 1.0
| [
| 2005
|-
| 1.1 WD
| [https://
| 2006-08-07
|-
Line 40 ⟶ 43:
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.)
All transfer types are single objects, serialized using JSON.<ref name="json-rpc1">
* <code>method</code> - A
* <code>params</code> - An
* <code>id</code> - A string or non-fractional number used to match the response with the request that it is replying to.<ref>{{cite web|url=https://www.jsonrpc.org/specification|title=JSON-RPC 2.0 Specification|quote=id: An identifier established by the Client that MUST contain a String, Number, 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 Numbers SHOULD NOT contain fractional parts}}</ref> This member may be omitted if no response should be returned.<ref>{{cite web|url=https://www.jsonrpc.org/specification|title=JSON-RPC 2.0 Specification|quote=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. Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params", "Internal error").}}</ref>
The receiver of the request must reply with a valid response to all received requests. A response
* <code>result</code> - The data returned by the invoked method. If an error occurred while invoking the method, this member must not exist.<ref>{{cite web|url=https://www.jsonrpc.org/specification|title=JSON-RPC 2.0 Specification|quote=result: This member is REQUIRED on success. This 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.
}}</ref>
* <code>error</code> - An error object if there was an error invoking the method, otherwise this member must not exist.<ref>{{cite web|url=https://www.jsonrpc.org/specification|title=JSON-RPC 2.0 Specification|quote=error: This member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during invocation. The value for this member MUST be an Object as defined in section 5.1.
}}</ref> The object must contain members ''code'' (integer) and ''message'' (string).<ref>{{cite web|url=https://www.jsonrpc.org/specification|title=JSON-RPC 2.0 Specification|quote=Error object: When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members: (code) - A Number that indicates the error type that occurred. 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 is defined by the Server (e.g. detailed error information, nested errors etc.).}}</ref> An optional ''data'' member can contain further server-specific data. There are pre-defined error codes which follow those defined for XML-RPC.
▲The receiver of the request must reply with a valid response to all received requests. A response must contain the properties mentioned below.
* <code>id</code> - The id of the request it is responding to.
Line 57 ⟶ 63:
=== Version 2.0 ===
Request and response:
<
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
</syntaxhighlight>
Notification (no response):
<
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
</syntaxhighlight>
=== Version 1.1 (Working Draft) ===
Request and response:
<
--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}
</syntaxhighlight>
=== Version 1.0 ===
Request and response:
<
--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}
</syntaxhighlight>
== See also ==
* [[gRPC]] - cross-platform binary RPC protocol
* [[SOAP]] - a messaging protocol
▲* [[JSON-WSP]] - a JSON-RPC inspired protocol with a service description specification.
* [https://labs.omniti.com/labs/jsend JSend specification which defines only format of response]▼
== References ==
<references responsive="0" />
==
* {{Official website}}
* [https://groups.google.com/group/json-rpc JSON-RPC Google Group] discussing topics of and around the protocol
* [http://www.simple-is-better.org/json-rpc/ JSON-RPC specifications, MNlinks etc.]
* [http://www.simple-is-better.org/json-rpc/transport_http.html HTTP transport] description for JSON-RPC-2
* [https://open-rpc.org OpenRPC Specification] Service description format for JSON-RPC. (open-api, but for json rpc)
▲* [https://
{{DEFAULTSORT:Json-Rpc}}
| |||