JSON-RPC — Opsalis Learn

What Is JSON-RPC?

JSON-RPC is a stateless, lightweight remote procedure call (RPC) protocol that uses JSON as its data format. The current version, JSON-RPC 2.0, defines a simple and elegant contract: a client sends a JSON object with a method name, optional params, and a request id. The server responds with a JSON object containing either a result or an error, along with the matching id. That is the entire protocol.

Unlike REST, which is resource-oriented (you operate on nouns), JSON-RPC is action-oriented (you call named methods). There are no URL paths to design, no HTTP verbs to choose, no status codes to interpret. You have one endpoint, and every call specifies which method to run. This makes JSON-RPC ideal for APIs that are naturally procedural — "calculate this," "convert that," "look up X" — rather than CRUD-oriented.

One of JSON-RPC's most useful features is batch requests. A client can send an array of request objects in a single HTTP call, and the server returns an array of responses. Each request in the batch is independent — some may succeed while others fail. This is valuable when you need to make multiple related calls and want to minimize network round trips.

JSON-RPC is transport-agnostic — the spec says nothing about how messages are delivered. While HTTP POST is the most common transport, JSON-RPC works equally well over WebSocket, TCP, Unix sockets, or even message queues. If you are in the blockchain space, you already use JSON-RPC: Ethereum nodes (Geth, Erigon), Bitcoin Core, and Solana all expose their APIs as JSON-RPC. It is also the protocol behind the Language Server Protocol (LSP) used by every modern code editor.

How JSON-RPC Works with Opsalis

JSON-RPC APIs are method-based rather than resource-based, so the handler maps each method to an OpenAPI endpoint that consumers can call naturally.

Owner provides a method list — a JSON file listing each method name along with its parameter schemas and response schemas. Upload it via the handler dashboard.
Handler constructs JSON-RPC requests. When a consumer calls the generated OpenAPI endpoint, the handler builds a properly formatted JSON-RPC 2.0 request: { "jsonrpc": "2.0", "method": "...", "params": {...}, "id": 1 } and sends it to the owner's server.
Handler extracts the result. The JSON-RPC response contains either a result field (success) or an error field (failure). The handler extracts the relevant data and returns clean JSON to the consumer.

Your JSON-RPC server stays untouched. Keep your existing methods, your existing endpoint. The handler speaks native JSON-RPC 2.0 to your server and presents a REST-style OpenAPI interface to consumers.

Demo API: World Countries and Currencies

This demo uses a World Countries and Currencies dataset — 250 countries and territories with 180 currencies, including ISO codes, capitals, regions, populations, languages, calling codes, and exchange rates. Methods include lookups by country code, currency code, region, and full-text search. A practical dataset that demonstrates JSON-RPC's strengths in procedural, lookup-style operations.

← Owner Guide

Code Example

Look up a country by ISO code

# JSON-RPC 2.0 request to get country details
curl http://localhost:4005/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "getCountryByCode",
    "params": { "code": "JP" },
    "id": 1
  }'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "code": "JP",
    "name": "Japan",
    "capital": "Tokyo",
    "region": "Asia",
    "population": 125836021,
    "currency": { "code": "JPY", "name": "Japanese Yen", "symbol": "¥" },
    "languages": ["Japanese"]
  },
  "id": 1
}

Batch request: look up three currencies at once

# JSON-RPC batch: multiple method calls in one HTTP request
curl http://localhost:4005/jsonrpc \
  -H "Content-Type: application/json" \
  -d '[
    { "jsonrpc": "2.0", "method": "getCurrency", "params": { "code": "USD" }, "id": 1 },
    { "jsonrpc": "2.0", "method": "getCurrency", "params": { "code": "EUR" }, "id": 2 },
    { "jsonrpc": "2.0", "method": "getCurrency", "params": { "code": "JPY" }, "id": 3 }
  ]'

Standard Error Codes

JSON-RPC 2.0 defines a set of standard error codes. Knowing these helps you debug issues quickly:

Code	Message	Meaning
`-32700`	Parse error	Invalid JSON received by the server
`-32600`	Invalid Request	JSON is valid but not a proper JSON-RPC request
`-32601`	Method not found	The requested method does not exist
`-32602`	Invalid params	Invalid method parameters
`-32603`	Internal error	Server-side error during execution

JSON-RPC at a Glance

Concept	Details
Transport	Any (HTTP, WebSocket, TCP, Unix socket)
Data format	JSON
Spec format	Method list with parameter/response schemas (JSON)
Request structure	`{ jsonrpc, method, params, id }`
Batch support	Yes — send array of requests, get array of responses
Best for	Blockchain nodes, procedural APIs, language servers, internal services