JSON-RPC: Difference between revisions

Revision as of 12:56, 10 November 2020

Latest revision as of 11:20, 5 June 2025

(18 intermediate revisions by 11 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 [[remote procedure callJSON]]-based [[Protocolwire (computing)|protocol]] encoded infor [[JSONremote procedure call]]s (RPC). It is similar to the [[XML-RPC]] protocol, defining only a few 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 asynchronously.

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

| [https://webwww.archivejsonrpc.org/web/20080517011921/http://json-rpc.org/wiki/specificationspecification_v1 Original version]

| 2005

|-

| 1.1 WD

| [https://web.archivejsonrpc.org/web/20100718181845/http:/historical/json-rpc.org/wd/JSON-RPC-1-1-WD-20060807wd.html Working draft]. Adds named parameters, adds specific error codes, and adds introspection functions.

| 2006-08-07

|-

Line 41 ⟶ 44:

All transfer types are single objects, serialized using JSON.<ref name="json-rpc1">{{Cite web |url=http://json-rpc.org/wiki/specification |title=specification - JSON-RPC - Trac<!-- Bot generated title --> |access-date=2008-05-14 |archive-url=https://web.archive.org/web/20080517011921/http://json-rpc.org/wiki/specification |archive-date=2008-05-17 |url-status=dead }}</ref> A request is a call to a specific method provided by a remote system. It can contain three members:

* <code>method</code> - A Stringstring with the name of the method to be invoked. Method names that begin with "rpc." are reserved for rpc-internal methods.

* <code>params</code> - An Objectobject or Arrayarray of values to be passed as parameters to the defined method. This member may be omitted.

* <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 can contain the members mentioned below.

* <code>result</code> - The data returned by the invoked method. This element is formatted as a JSON-stat object. 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.

Line 60 ⟶ 63:

=== Version 2.0 ===

Request and response:

<syntaxhighlight lang="javascriptjson">

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

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

</syntaxhighlight>

Notification (no response):

<syntaxhighlight lang="javascriptjson">

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

</syntaxhighlight>

Line 71 ⟶ 74:

=== Version 1.1 (Working Draft) ===

Request and response:

<syntaxhighlight lang="javascriptjson">

--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}

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

Line 78 ⟶ 81:

=== Version 1.0 ===

Request and response:

<syntaxhighlight lang="javascriptjson">

--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}

<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

Line 84 ⟶ 87:

== See also ==

* [[gRPC]] - cross-platform binary RPC protocol

* [[Remote procedure call]] (RPC)

* [[SOAP]] - a messaging protocol

* [[XML-RPC]]

* [[JSON-WSP]] - a JSON-RPC inspired protocol with a service description specification.

* [[gRPC]]

* [[SOAPjr]] - a hybrid of SOAP and JSON-RPC

* [[JSON-WSP]] - a JSON-RPC inspired protocol with a service description specification.

* [https://github.com/omniti-labs/jsend JSend] - a similar specification which defines only format of response

== References ==

Line 100:

* [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://github.com/omniti-labs/jsend JSend] - a similar specification which defines only format of response

{{DEFAULTSORT:Json-Rpc}}