JSON-RPC

JSON-RPC ( JavaScript Object Notation Remote Procedure Call ) is a protocol for calling remote methods in computer systems , similar to XML-RPC (but the data is sent in JSON instead of XML ). During the specification, care was taken to ensure that JSON-RPC does not contain any unnecessary complexity and that it can be used via various communication protocols . This means that it can be used very flexibly. In addition, the protocol supports asynchronous communication , as all inquiries and responses contain an ID, which enables easy assignment of responses to the corresponding inquiries.

JSON-RPC 1.0 allows requests in both directions ( peer-to-peer ), but most JSON-RPC 1.0 implementations only support one direction by default ( client-server model ).

JSON-RPC 2.0 uses a client-server model . Requests in both directions are possible by using a JSON-RPC server on both sides.

functionality

inquiry

A JSON-RPC call consists of a JSON object that is sent from the client to a server . Possible request types are

Request: The server should deliver an answer.
Notification: One-way communication, no response is expected from the server.
Batch Request: Several requests ( notifications or requests ) are sent together as a JSON array, the elements of which are then the individual request objects. (Available from version 2.0)

The following table lists the components of a request object.

component	description	comment
`jsonrpc`	A string with the name of the JSON-RPC version ("2.0")	From version 2.0
`method`	A string with the name of the function to be called.
`params`	An array or object containing the parameters to be passed to the function.	Object from version 2.0 possible
`id`	A unique identifier for the message. Can have any data type (usually an integer).

A notification is characterized by the fact that:

JSON-RPC version 2.0: idmissing
JSON-RPC version 1.0: id nullis

answer

In the case of a request, the server sends a response back to the client as a JSON object after the requested method has been executed. The components of a response object are listed in the following table.

Components	description	comment
`jsonrpc`	A string with the name of the JSON-RPC version ("2.0")	From version 2.0
`result`	The return object of the function if no RPC error occurred. Otherwise: Version 2.0: this field is omitted. Version 1.0: this field has the value `null`.
`error`	The error object if an RPC error occurred. Otherwise: Version 2.0: this field is omitted. Version 1.0: this field has the value `null`.
`id`	Contains the same value as `id`the request that caused this response.

If the server receives a notification, it executes the specified method, but does not send a response. If it receives a batch request, it executes the listed methods and sends a batch response (i.e. the responses to all requests in the batch request in one message).

Examples

In these examples stands -->for a message from the client to the server, and <--vice versa.

Version 2.0

A simple example with a request and a response:

--> { "jsonrpc": "2.0", "method": "gibAus", "params": ["Hallo JSON-RPC"], "id": 1}
<-- { "jsonrpc": "2.0", "result": "Hallo JSON-RPC", "id": 1}

Same example with "named parameters":

--> { "jsonrpc": "2.0", "method": "gibAus", "params": {"Nachricht": "Hallo JSON-RPC"}, "id": 2}
<-- { "jsonrpc": "2.0", "result": "Hallo JSON-RPC", "id": 2}

Further examples can be found at the end of the JSON-RPC 2.0 specification.

Version 1.0

A simple example with a request and a response

--> { "method": "gibAus", "params": ["Hallo JSON-RPC"], "id": 1}
<-- { "result": "Hallo JSON-RPC", "error": null, "id": 1}

This example shows part of the communication in a chat application. The chat service sends a notification for every message that the client should receive. The client sends a request to send a message and expects positive feedback to know that the message has been published.

...
--> {"method": "veröffentlicheNachricht", "params": ["Hallo an alle!"], "id": 99}
<-- {"result": 1, "error": null, "id": 99}
<-- {"method": "empfangeNachricht", "params": ["Benutzer1", "Wir unterhielten uns gerade"], "id": null}
<-- {"method": "empfangeNachricht", "params": ["Benutzer3", "Ich muss jetzt los, tschüss"], "id": null}
--> {"method": "veröffentlicheNachricht", "params": ["Ich habe eine Frage!"], "id": 101}
<-- {"method": "ändereStatus", "params": ["abwesend","Benutzer3"], "id": null}
<-- {"result": 1, "error": null, "id": 101}
...

history

The first version of JSON-RPC dates from 2005. Version 2.0 was adopted in 2010.

version	description	date
1.0	Original version	2005
Draft "1.1 WD"	Restricted to HTTP, named parameters, specific error codes and introspective functions added.	08/07/2006
Draft "1.1 Old"	Alternative (simplified) proposal for 1.1 WD.	05/06/2007
Draft "1.2"	Slightly modified version of 1.1 Alt. A later version was renamed to 2.0.	12/27/2007
2.0	current specification	2010

Implementations

JSON-RPC has been implemented in various programming languages including JavaScript , C ++ , C , C # , Java , Python, and PHP . Since JSON consists of Unicode characters, JSON-RPC can also be implemented relatively easily in other programming languages.

distribution

Wherever JSON-RPC is used, it is rarely an issue in public. On July 31, 2019, Google announced that from August 12, 2020, only REST can be used to access the Google APIs instead of JSON-RPC .

Individual evidence

↑ specification - JSON-RPC - Trac ( Memento of the original from May 17, 2008 in the Internet Archive ) Info: The archive link was inserted automatically and not yet checked. Please check the original and archive link according to the instructions and then remove this notice. @1@ 2
↑ Archive link ( Memento of the original from May 17, 2008 in the Internet Archive ) Info: The archive link was automatically inserted and not yet checked. Please check the original and archive link according to the instructions and then remove this notice. @1@ 2
↑ http://www.simple-is-better.org/json-rpc/jsonrpc20.html
↑ RFC 4627 application / json
↑ Rainald Menge-Sonnentag: Google sends JSON-RPC access into retirement. In: heise online. August 2, 2019, accessed August 4, 2019 .

[1] specification - JSON-RPC - Trac ( Memento of the original from May 17, 2008 in the Internet Archive ) Info: The archive link was inserted automatically and not yet checked. Please check the original and archive link according to the instructions and then remove this notice. @1@ 2

[2] Archive link ( Memento of the original from May 17, 2008 in the Internet Archive ) Info: The archive link was automatically inserted and not yet checked. Please check the original and archive link according to the instructions and then remove this notice. @1@ 2

[3] ttp://www.simple-is-better.org/json-rpc/jsonrpc20.html

[4] RFC 4627 application / json

[5] Rainald Menge-Sonnentag: Google sends JSON-RPC access into retirement. In: heise online. August 2, 2019, accessed August 4, 2019 .