Quarkus JSON-RPC

Expose your Java methods as JSON-RPC 2.0 endpoints — with a single annotation.

Quarkus JSON-RPC discovers classes annotated with @JsonRPCApi at build time and makes their public methods callable via the JSON-RPC 2.0 protocol. Choose your transport: WebSocket for browser and network clients, or JSONL over Unix domain sockets for local IPC. No manual routing, no protocol plumbing.

In a Glance

@JsonRPCApi
public class GreetingService {

    public String hello(String name) {
        return "Hello " + name;
    }
}

Connect to ws://localhost:8080/json-rpc and send:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "GreetingService#hello",
  "params": { "name": "World" }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "Hello World"
}

Installation

The extension is split into a transport-agnostic core and pluggable transport modules. Add the transport you need:

WebSocket transport

For browser clients, network clients, or any WebSocket-based integration:

<dependency>
    <groupId>io.quarkiverse.json-rpc</groupId>
    <artifactId>quarkus-json-rpc-websocket</artifactId>
    <version>2.0.0</version>
</dependency>

Domain socket transport

For local IPC using JSONL (newline-delimited JSON) over Unix domain sockets:

<dependency>
    <groupId>io.quarkiverse.json-rpc</groupId>
    <artifactId>quarkus-json-rpc-domain-socket</artifactId>
    <version>2.0.0</version>
</dependency>

Both transports can be used simultaneously in the same application. The @JsonRPCApi annotation and all core features work identically regardless of transport.

Key Features

Pluggable transports: WebSocket for browser and network clients, or JSONL over Unix domain sockets for local IPC. Both transports share the same @JsonRPCApi annotation and core engine - add a dependency and you’re done.
Build-time discovery: All @JsonRPCApi classes are found at build time via Jandex — no runtime classpath scanning, full ahead-of-time compilation and GraalVM native image support.
Reactive and blocking: Return plain types for blocking execution, Uni<T> for async, or Multi<T> for streaming subscriptions. Fine-tune with @Blocking, @NonBlocking, or @RunOnVirtualThread.
Server push: Inject JsonRPCBroadcaster to send notifications to all connected clients or target a specific session.
Flexible parameters: Call methods with named parameters (JSON object) or positional parameters (JSON array).
POJO support: Complex types are serialized and deserialized automatically via Jackson, including nested objects, collections, and Java time types.
Security: Secure your endpoints with standard Jakarta security annotations (@RolesAllowed, @Authenticated, etc.) or Quarkus HTTP auth policies — opt-in, no changes needed for unsecured use cases.
Health check: When SmallRye Health is on the classpath, a readiness check is registered automatically — reporting endpoint status and active connection count.
OpenRPC service discovery: An OpenRPC 1.3.2 document is generated at build time and served at /json-rpc/openrpc.json, describing all methods, parameters, and return types with JSON Schema — enabling automatic client generation and documentation.
Timeouts: Protect against hanging methods with a global timeout or per-method @Timeout via MicroProfile Fault Tolerance.
JavaScript client: Optionally generate a typed JavaScript proxy for all your endpoints, ready to import from Quarkus Web Bundler or any ES module environment.
Dev UI: An interactive method browser and tester is available in the Quarkus Dev UI during development.

What’s Next?

Page Description

Page	Description
Creating an API	Annotate your first class and understand method discovery rules.
Execution Modes & Return Types	Blocking, non-blocking, `Uni`, `Multi`, `CompletionStage` — how the extension dispatches your methods.
Parameters	Named vs. positional parameters and supported types.
Streaming with Multi	Subscribe to server-sent streams and manage subscriptions.
Broadcasting	Push notifications to clients from any CDI bean.
Security	Secure endpoints with annotations or HTTP auth policies.
Concurrency & Session Isolation	Connection isolation, shared bean instances, threading model, and tuning for production.
Connection Lifecycle Events	React to client connect and disconnect via CDI events.
Timeouts	Protect against hanging methods with global or per-method timeouts.
Metrics	Automatic request timing and connection tracking with Micrometer.
Health Check	Automatic readiness health check with active connection count.
OpenRPC Service Discovery	Machine-readable API description with JSON Schema for all methods.
JavaScript Client	Generate a typed JavaScript proxy for calling your endpoints from the browser.
Domain Socket Transport	Serve JSON-RPC over Unix domain sockets using JSONL framing for local IPC.
Configuration Reference	All available configuration properties.

Creating an API

Annotate your first class and understand method discovery rules.

Execution Modes & Return Types

Blocking, non-blocking, Uni, Multi, CompletionStage — how the extension dispatches your methods.

Parameters

Named vs. positional parameters and supported types.

Streaming with Multi

Subscribe to server-sent streams and manage subscriptions.

Broadcasting

Push notifications to clients from any CDI bean.

Security

Secure endpoints with annotations or HTTP auth policies.