JSON‑RPC Overview
Goa supports JSON‑RPC 2.0 over multiple transports:
- HTTP (unary requests and responses)
- HTTP Server‑Sent Events (SSE) for server‑initiated streaming
- WebSocket for bidirectional streaming
Key properties:
- Batch requests and notifications are supported where applicable.
- The same JSON‑RPC HTTP route can serve SSE by content negotiation using the
Acceptheader (application/jsonvs.text/event-stream). - JSON‑RPC WebSocket uses a single connection per service, shared by all methods.
Related concepts: see Transports for the matrix of allowed combinations within one service and per method.
Topics in this section
- IDs and Envelope Mapping
- HTTP and SSE Semantics
- WebSocket Streaming
- Batching and Notifications
- Error Mapping
If you prefer a guided build, start with the tutorial: Basic JSON‑RPC Service.
Method names
On the wire, the JSON‑RPC method value is the DSL method name (for example: add). Each service has a single JSON‑RPC endpoint, so names are scoped to the service and do not need a service.method prefix.
Transport summary
| Transport | Connection | Patterns | Batching | Notifications |
|---|---|---|---|---|
| HTTP | Request/response | Non‑streaming (unary) | Yes (array body) | Client → Yes |
| SSE | Long‑lived HTTP resp. | Server streaming, mixed results | Not applicable | Server → Yes |
| WebSocket | Persistent (full‑duplex) | Client streaming, server streaming, bidirectional | Not typical (message‑oriented) | Both directions |
Notes:
- SSE shares the same route as HTTP. The client selects SSE via
Accept: text/event-streamand the method must declare a streaming result (or mixed results). - WebSocket is enabled by using
GETon the JSON‑RPC endpoint. Non‑streaming methods are not supported over JSON‑RPC WebSocket.