JSON-RPC — Lightweight Remote Procedure Calls Using JSON

In this tutorial, you will learn about JSON. We cover key concepts, practical examples, and best practices to help you master this topic.

JSON-RPC is a lightweight RPC protocol that uses JSON for message encoding, supporting both positional and named parameters with standardized error responses.

What You'll Learn

• JSON-RPC 2.0 message structure
• Batch requests and notifications
• Error codes and error handling

Why It Matters

JSON-RPC combines the simplicity of RPC with the efficiency of JSON, making it ideal for lightweight services where REST's resource model adds unnecessary complexity.

Code Examples

// JSON-RPC 2.0 Request
{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": {"subtrahend": 23, "minuend": 42},
  "id": 1
}

// JSON-RPC 2.0 Response
{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 1
}

// JSON-RPC 2.0 Error Response
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {"method": "nonExistent"}
  },
  "id": 1
}

// JSON-RPC Notification (no response expected)
{
  "jsonrpc": "2.0",
  "method": "logEvent",
  "params": {"event": "page_view"}
}
// Note: no "id" field means no response

# JSON-RPC client
import requests

def json_rpc_call(url, method, params=None):
    payload = {
        "jsonrpc": "2.0",
        "method": method,
        "params": params or {},
        "id": 1
    }
    response = requests.post(url, json=payload)
    result = response.json()
    if "error" in result:
        raise Exception(f"RPC Error {result['error']['code']}: {result['error']['message']}")
    return result["result"]

url = "https://api.example.com/jsonrpc"
print(json_rpc_call(url, "add", {"a": 10, "b": 5}))
print(json_rpc_call(url, "getUser", {"id": 123}))

Common Mistakes

1. Forgetting the "jsonrpc" Version Field

The "jsonrpc": "2.0" field is required in every request.

2. Sending Notifications Without Distinction

Notifications have no id. Clients must not expect responses.

3. Using Incorrect Error Codes

Standard codes: -32700 (parse), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal).

4. Mixing Parameter Styles

Use either positional (array) or named (object) params, not both.

5. Not Handling Batch Request Ordering

Batch responses must be returned in the same order as requests.

Practice Questions

1. What is the required field in every JSON-RPC 2.0 request?
2. How does a notification differ from a regular request?
3. What are the standard JSON-RPC error codes?
4. Can JSON-RPC send multiple requests at once?
5. How does JSON-RPC handle unknown methods?

Answers:

1. "jsonrpc": "2.0".
2. Notifications have no id field and the server does not return a response.
3. -32700 (parse), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal).
4. Yes, through batch requests (array of request objects).
5. Returns an error response with code -32601.

Challenge: Build a JSON-RPC service with methods for user CRUD operations. Implement batch requests and notifications for logging.

FAQ

What's Next

Build the Web Services Project to apply all concepts, or explore API Documentation with OpenAPI.