Mastering JSON-RPC 2.0: Requests, Responses, Notifications, and Batch Calls

Introduction

JSON-RPC is a simple, lightweight, stateless remote procedure call (RPC) protocol that enables different systems to communicate using a standardized data format. Since its publication by the JSON-RPC Working Group in 2010, the 2.0 version has become a core protocol for many applications.

Request Object

A request object sent to the server represents an RPC call and contains the following members: jsonrpc: string, the JSON-RPC version (must be "2.0"). method: string, the name of the remote method to invoke. params: structured value (array or object) with parameters for the method; optional if the method takes no parameters. id: a unique identifier (string, number, or null) for the client request; omitted for notifications.

Example request:

{
  "jsonrpc": "2.0", // required, protocol version
  "method": "user.register", // required, target method
  "params": {
    "username": "[email protected]",
    "password": "h@sh123",
    "profile": { "role": "admin" }
  },
  "id": "reg_001" // required for non‑notification requests
}

Response Object

The server returns a JSON object containing these members: jsonrpc: string, must be "2.0". result: present only when the request succeeds, containing the method's return value. error: present only when the request fails; it is an object with code (integer), message (string), and optional data (any type) providing additional details. id: the same identifier as in the request, used to match response to request.

Successful response example:

{
  "jsonrpc": "2.0",
  "result": {
    "userId": 10086,
    "token": "eyJhbGciOiJSUzI1NiJ9",
    "expire": 1687521600
  },
  "id": "reg_001"
}

Error response example:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602, // standard error code (invalid params)
    "message": "密码强度不足",
    "data": {
      "rules": "需8位以上，含大小写字母与数字",
      "invalid_field": "password"
    }
  },
  "id": "reg_001"
}

Notifications

Notifications are special requests that omit the id field, meaning the client does not expect a response. They are useful for fire‑and‑forget scenarios such as logging.

{
  "jsonrpc": "2.0",
  "method": "user.login",
  "params": ["User logged in"]
}

Batch Requests

JSON-RPC 2.0 supports sending an array of request objects in a single call; the server returns an array of corresponding responses.

Batch request example:

[
  {
    "jsonrpc": "2.0",
    "method": "add",
    "params": [1, 2],
    "id": 1
  },
  {
    "jsonrpc": "2.0",
    "method": "subtract",
    "params": [5, 3],
    "id": 2
  }
]

Batch response example (all successful):

[
  { "jsonrpc": "2.0", "result": 3, "id": 1 },
  { "jsonrpc": "2.0", "result": 2, "id": 2 }
]

Batch response with an error:

[
  { "jsonrpc": "2.0", "result": 3, "id": 1 },
  { "jsonrpc": "2.0", "error": { "code": -32601, "message": "Method not found" }, "id": 2 }
]

Typical Applications

AI toolchain integration : The MCP protocol extends JSON-RPC to support function‑calling mechanisms for large‑model plugins, enabling parameter passing and context management.

Blockchain node interaction : Ethereum exposes core APIs (e.g., eth_getBalance) via JSON‑RPC, allowing clients to query blockchain state.

IoT device communication : Sensors use long‑lived HTTP connections to report data; JSON’s lower parsing overhead compared to XML makes it suitable for low‑power devices.