What is JSON-RPC? Protocol, Examples, REST Comparison

What is JSON-RPC?

JSON-RPC is a lightweight remote procedure call (RPC) protocol that encodes requests and responses as JSON. The client names a method and its parameters, the server runs it and returns a result or an error. It is stateless and transport agnostic: the JSON-RPC 2.0 specification (dated 2010) describes messages, not how they travel.

You meet it in Ethereum nodes, the Language Server Protocol behind code editors and the Model Context Protocol used by AI tools. All three use JSON-RPC 2.0 messages.

How a JSON-RPC call works

A request has four members: jsonrpc (always "2.0"), method (the name to call), params (optional, an array for positional or an object for named arguments) and id (a string or number you choose, echoed back in the reply).

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

A successful reply carries the same id and a result:

{"jsonrpc": "2.0", "result": 19, "id": 1}

A failed call carries an error object with a numeric code and a message instead of a result:

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}

Over HTTP this is one POST to a single URL, with the method name in the body instead of the path. You can try it with curl: send the request object as the body with Content-Type: application/json.

Notifications and batch requests

A request without an id is a notification: the server must not reply, so the client never learns whether it worked.

{"jsonrpc": "2.0", "method": "log", "params": {"level": "info"}}

To send several calls at once, put the request objects in an array. The server answers with an array of responses, and the spec allows them in any order, so match each response to its request by id.

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2, 4], "id": 1},
  {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 2}
]

Standard error codes

JSON-RPC vs REST vs gRPC

Choose REST when your API is about resources and you want HTTP caching and status codes to work for you. Choose JSON-RPC when the natural model is "do this action", for example sending a transaction or asking a language server for completions.

Common mistakes

• Treating HTTP 200 as success. Many servers return 200 even when the body holds an error. Check the body.
• Reusing an id within one connection. Replies cannot be matched to requests, which is painful with batches.
• Assuming batch responses arrive in order. The spec does not promise it.
• Sending a call as a notification. Leaving out id means you will never see the result or the error.
• Using null as an id. The spec discourages it, and MCP forbids it.
• Putting credentials in the payload. Authenticate at the transport layer instead, for example with a bearer token in the Authorization header.

Testing and monitoring JSON-RPC endpoints

Because errors usually come back with status 200, a plain status check will miss them. Assert on the body instead: error is absent, result is present, and id matches. LoadFocus API monitoring supports assertions on status code, body and response time, and free checks run every 5 minutes.

For load tests, remember that a batch is one HTTP request but many method calls, so it loads your backend differently from the same calls sent one by one. Use unique ids per call and test the methods that touch your database or a blockchain node first. LoadFocus load testing runs JMeter and k6 scripts that can post JSON bodies, and this walkthrough on load testing APIs covers the setup. The API endpoint entry explains what you are pointing the test at.

FAQ: JSON-RPC

Is JSON-RPC still used?

Yes. Ethereum clients expose a JSON-RPC interface, the Language Server Protocol uses it between editors and language servers, and the Model Context Protocol builds on JSON-RPC 2.0. It is less common for public web APIs, where REST dominates.

JSON-RPC vs REST: which is better?

Neither in general. REST fits resource-oriented public APIs. JSON-RPC fits action-oriented interfaces where you call a method, and it works over transports other than HTTP.

Does JSON-RPC use HTTP status codes?

The specification does not define them. Errors are reported in the response body, and many servers return 200 either way. Some implementations map errors to HTTP codes, so check the server's documentation.

How do I authenticate a JSON-RPC API?

The protocol has no authentication of its own. Use whatever the transport offers: an API key or bearer token in a header over HTTP, or a connection-level mechanism over WebSocket.

What is the difference between JSON-RPC 1.0 and 2.0?

Version 2.0 identifies messages with the jsonrpc member and marks a notification by leaving out id (1.0 used a null id). It also defines named parameters, batch requests and a reserved range of error codes. The two versions may not interoperate, so use 2.0 for anything new.

Can JSON-RPC push data from the server?

Over a persistent connection such as WebSocket, yes: either side can send notifications. Over plain HTTP, only the client starts a request.