NAS-132232 / 25.04-RC.1 / API doc for JSON-RPC 2.0 protocol (by themylogin)

src/middlewared_docs/docs/index.rst

@@ -4,6 +4,7 @@ Contents
 .. toctree::
    :maxdepth: 1
 
+   jsonrpc.rst
    api_methods.rst
    api_events.rst
    jobs.rst

src/middlewared_docs/docs/jsonrpc.rst

@@ -0,0 +1,167 @@
+JSON-RPC 2.0 over WebSocket API
+===============================
+
+Overview
+--------
+
+The TrueNAS API implements the `JSON-RPC 2.0 <https://www.jsonrpc.org/specification>`_ 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 <https://www.jsonrpc.org/specification>`_ 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:
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "method": "<method_name>",
+     "params": [<parameters>]
+   }
+
+Example Request:
+^^^^^^^^^^^^^^^^
+
+Calling the ``system.info`` method:
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "method": "system.info",
+     "params": []
+   }
+
+JSON-RPC Response Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The TrueNAS API will respond with a standard JSON-RPC response:
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "result": {<result_data>}
+   }
+
+Example Response:
+^^^^^^^^^^^^^^^^^
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "result": {
+       "version": "TrueNAS-25.04",
+       "uptime": "15 days"
+     }
+   }
+
+Error Response
+~~~~~~~~~~~~~~
+
+If an error occurs, the response format is:
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 1,
+     "error": {
+       "code": -32001,
+       "message": "method call error",
+       "data": {<error_details>}
+     }
+   }
+
+Custom Error Codes
+^^^^^^^^^^^^^^^^^^
+
++---------------+-------------------------------------+----------------+
+| 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: json
+
+   {
+     "jsonrpc": "2.0",
+     "method": "collection_update",
+     "params": [<update_data>]
+   }
+
+Example Notification:
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code:: json
+
+   {
+     "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.