JSON-RPC 2.0 over WebSocket API

Overview

The TrueNAS API implements the JSON-RPC 2.0 protocol over WebSocket for communication between clients and the TrueNAS server. This allows real-time interaction, including method calls and event notifications.

JSON-RPC 2.0 Protocol

Communication Mechanism

• Messages are exchanged using the WebSocket protocol.

• The client initiates a WebSocket connection to the TrueNAS API endpoint.

• The API follows the JSON-RPC 2.0 specification for request-response messaging.

Request and Response Format

JSON-RPC Request Structure

A typical method call request from the client to TrueNAS follows this structure:

{
  "jsonrpc": "2.0",
  "id": number | string,
  "method": string,
  "params": array
}

Example Request:

Calling the system.info method:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "system.info",
  "params": []
}

JSON-RPC Response Structure

The TrueNAS API will respond with a standard JSON-RPC response:

{
  "jsonrpc": "2.0",
  "id": number | string,
  "result": any
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": "TrueNAS-25.04",
    "uptime": "15 days"
  }
}

Error Response

If an error occurs, the response format is:

{
  "jsonrpc": "2.0",
  "id": number | string,
  "error": {
    "code": number,
    "message": string | null,
    "data": {
      "error": number,
      "errname": string,
      "reason": string,
      "trace": {
        "class": string,
        "frames": array,
        "formatted": string,
        "repr": string
      } | null,
      "extra": array,
      "py_exception": string
    }
  }
}

Custom Error Codes

The following custom error codes can be returned in addition to the codes defined by the JSON-RPC 2.0 specification.

Error Code	Message	Description
-32000	“too many concurrent calls”	The client has exceeded the allowed concurrent requests.
-32001	“method call error”	There was an error executing the requested method.

Event Notifications

If the server needs to notify a connected client of an event, it sends a JSON-RPC Notification message with the collection_update method.

JSON-RPC Notification Structure

collection_update

 {
   "jsonrpc": "2.0",
   "method": "collection_update",
   "params": {
     "msg": string,
     "collection": string,
     "id": any,
     "fields": {
       "id": string,
       "state": string,
       "progress": {
         "percent": number,
         "description": string
       },
       "result": any,
       "exc_info": {
         "type": string,
         "extra": array | null,
         "repr": string
       },
       "error": string,
       "exception": string
     },
     "extra": object
   }
 }

notify_unsubscribed

 {
   "jsonrpc": "2.0",
   "method": "notify_unsubscribed",
   "params": {
     "collection": string,
     "error": {
       "error": number,
       "errname": string,
       "reason": string,
       "trace": {
         "class": string,
         "frames": array,
         "formatted": string,
         "repr": string
       } | null,
       "extra": array,
       "py_exception": string
     }
   }
 }

Example Notification:

{
  "jsonrpc": "2.0",
  "method": "collection_update",
  "params": {
    "collection": "disk.query",
    "event": "CHANGED",
    "fields": {
      "name": "sda",
      "status": "HEALTHY"
    }
  }
}

Important Notes on Notifications

• No Response Required: These notifications do not require a response from the client.

• Event-Driven: Notifications are used for updates such as status changes, new log entries, or alerts.

Limitations

• Batch Requests Are Not Supported: Each request must be sent individually; batch calls are not allowed.

• Error Handling: Custom error codes are provided for handling specific issues.