HTTP

The Axum adapter is the reference implementation for this experimental API. The protocol is not plain REST and is not compatible with tRPC's client.

Queries and mutationsCopy Anchor Link

For an endpoint mounted at /rspc:

Nested procedure names use dots, for example users.list. A query with a string input can be called with:

curl --get 'http://localhost:4000/rspc/echo' \
  --data-urlencode 'input="hello"'

A mutation with an object input uses:

curl 'http://localhost:4000/rspc/createUser' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Ada"}'

These calls assume the corresponding procedures exist. Inputs are JSON values, not arbitrary form fields. Native form submissions and multipart uploads need separate handling.

Responses and errorsCopy Anchor Link

The adapter wraps results in a JSON-RPC-style envelope. Clients read result.type and result.data; they do not receive the resolver value as the whole response body. A successful response has a response result type. Procedure failures use an error result type.

An HTTP status alone is not enough to identify success. Resolver failures can be carried in an HTTP 200 response. Decode the envelope and test both application errors and protocol errors when implementing a client.

Use the adapter implementation and its jsonrpc module as the exact protocol reference. Error representation differs between the old and experimental APIs.

WebSocketsCopy Anchor Link

With the ws feature enabled, Axum accepts a WebSocket connection at /rspc/ws. Requests carry an ID, an operation method, and parameters containing the procedure path and input. Response IDs associate results with requests; subscriptions deliver multiple events and need cancellation handling.

WebSocket messages are not HTTP GET or POST requests after the upgrade. Use a client from the same protocol generation rather than constructing messages from an older guide.

Authentication and cachingCopy Anchor Link

HTTP transports can send cookies or authorization headers through a custom fetch function. See client authentication.

Do not cache authenticated responses in a shared CDN by default. A safe cache policy must account for the user, procedure path, input, and response headers. A GET request does not imply that its response is public.

Serverless and other serversCopy Anchor Link

rspc does not provide a deployment adapter for every serverless platform. If a platform supports Axum through an HTTP bridge, verify its request, response, and runtime requirements. WebSocket subscriptions also need a platform that supports long-lived connections.

For another Rust web framework, implement the same decoding and response contract around the built procedures. See custom integrations. Do not assume that returning serialized resolver output is protocol compatible.