JSON-RPC is a widely adopted standard that describes structured messages for communication between a client and server. The current version is 2.0 (published in 2010).
It combines two technologies:
Note that “client” and “server” are used here to describe the two ends of the communication. In practice, the client and server could be any two programs that communicate with each other. Client and server roles could be reversed at different times in their lifecycle.
JSON-RPC is used in many different contexts, including:
Request message
Request messages ask for an action (method) to be
performed. The server must reply to a request with a response
message.
jsonrpc (string): the version of
the JSON-RPC protocol.method (string): the name of the
action to be performedparams (object | array):
(optional) the parameters for the methodid (number | string): a unique
identifier for the requestA result and an error are mutually exclusive. If a response includes a result, it must not include an error, and vice versa.
A result can be any JSON value, including null. An
error is an object with a code and a
message property. An error can also include a
data property with additional information about the
error.
Response message
Response messages are the reply to a request. They include the id of the request they are replying to and a result or an error.
jsonrpc (string): the version of
the JSON-RPC protocol.result (any): the result of the
methoderror (object): an error
messageid (number | string): the id of
the request being replied toNotification message
Notification messages inform the other end about something that happened, and do not expect a reply.
jsonrpc (string): the version of
the JSON-RPC protocol.method: the name of the action
that happenedparams: (optional) the parameters
for the methodRequest & Response
Here, a client asks the server to add two numbers together. The server replies with the result.
Request:
{
"jsonrpc": "2.0",
"method": "add",
"params": [12, 5],
"id": 1
}Response:
{
"jsonrpc": "2.0",
"result": 17,
"id": 1
}Here, a client asks the server to add a number to a string. The server replies with an error.
Request:
{
"jsonrpc": "2.0",
"method": "add",
"params": [3, "cat"],
"id": 2
}Response:
{
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Invalid params",
"data": "Cannot add a number to a string"
},
"id": 2
}Notification
Here, the server informs the client that a user has logged in.
The server doesn’t reply to this message but may use this
notification to (e.g.) update the lastLoggedIn field in
the user’s record or trigger a workflow.
{
"jsonrpc": "2.0",
"method": "userLoggedIn",
"params": {
"userId": 123
}
}JSON-RPC also supports batch requests, where a client sends multiple requests in a single message, and the server replies with multiple responses.
Request:
[
{
"jsonrpc": "2.0",
"method": "add",
"params": [12, 5],
"id": 1
},
{
"jsonrpc": "2.0",
"method": "add",
"params": [3, "cat"],
"id": 2
}
]Response:
[
{
"jsonrpc": "2.0",
"result": 17,
"id": 1
},
{
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Invalid params",
"data": "Cannot add a number to a string"
},
"id": 2
}
]JSON-RPC is a widely adopted standard that describes structured messages for communication between a client and server. The current version is 2.0.
It combines two technologies:
Request message
Request messages ask for an action (method) to be
performed. The server must reply to a request with a response
message.
jsonrpc (string): the version of
the JSON-RPC protocol.method (string): the name of the
action to be performedparams (object | array):
(optional) the parameters for the methodid (number | string): a unique
identifier for the requestResponse message
Response messages are the reply to a request. They include the id of the request they are replying to and a result or an error.
jsonrpc (string): the version of
the JSON-RPC protocol.result (any): the result of the
methoderror (object): an error
messageid (number | string): the id of
the request being replied toA result and an error are mutually exclusive. If a response includes a result, it must not include an error, and vice versa.
A result can be any JSON value, including null. An
error is an object with a code and a
message property. An error can also include a
data property with additional information about the
error.
Notification message
Notification messages inform the other end about something that happened, and do not expect a reply.
jsonrpc (string): the version of
the JSON-RPC protocol.method: the name of the action
that happenedparams: (optional) the parameters
for the methodJSON-RPC is a standard for communication between a client and server.
Official spec: https://www.jsonrpc.org/specification
method) to be performed. Besides the method, the
request message can include parameters for the method. It always
includes an id.JSON-RPC is a standard for communication between a client and server.
method) to be performed.Official spec: https://www.jsonrpc.org/specification
JSON-RPC is a standard for communication between a client and server.
Official spec: https://www.jsonrpc.org/specification