Skip to content

Migrate TrueNAS apps to JSON-RPC 2.0 WebSocket API #889

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
jaycollett wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Migrate TrueNAS apps to JSON-RPC 2.0 WebSocket API #889

jaycollett wants to merge 1 commit into from

Conversation

@jaycollett
Copy link
Contributor

@jaycollett jaycollett commented Jan 29, 2026

Summary

TrueNAS is deprecating the REST API (api/v2.0/) in version 26.04, requiring migration to JSON-RPC 2.0 over WebSocket. This PR updates TrueNAS CORE and SCALE apps to support the new API.

Dependency

⚠️ This PR requires linuxserver/Heimdall#1538 to be merged first

That PR adds the WebSocket client infrastructure this PR depends on.

Changes

New Files

  • TrueNASCORE/TrueNASApiTrait.php - Shared trait for WebSocket/REST API communication

Updated Files

  • TrueNASCORE/TrueNASCORE.php - Updated to use the shared trait
  • TrueNASCORE/config.blade.php - Added API mode selector
  • TrueNASSCALE/TrueNASSCALE.php - Updated to use the shared trait
  • TrueNASSCALE/config.blade.php - Added API mode selector

Features

API Mode Selection

Users can choose between three modes:

  • Auto (default) - Tries WebSocket first, falls back to REST if unavailable
  • WebSocket Only - For TrueNAS 25.04+ (fails if WebSocket unavailable)
  • REST Only - For older TrueNAS versions or troubleshooting

API Mapping

REST Endpoint JSON-RPC Method Purpose
core/ping core.ping Connection test
system/info system.info Get uptime
alert/list alert.list Get alerts

Backward Compatibility

  • Default mode is "Auto" which maintains compatibility with all TrueNAS versions
  • Existing configurations continue to work without modification
  • REST API support is preserved for users on older TrueNAS versions
TrueNAS Version Recommended Mode
< 25.04 REST Only
25.04 Auto
26.04+ WebSocket Only (or Auto)

References

Test Plan

  • Tested with TrueNAS SCALE 25.10.1 in WebSocket mode
  • Verified API mode switching works correctly
  • Confirmed livestats (uptime, alerts) work via WebSocket
  • Tested with self-signed certificates
  • Verified backward compatibility with REST mode

@jaycollett
Migrate TrueNAS apps to JSON-RPC 2.0 WebSocket API
f1fc196 
TrueNAS is deprecating the REST API (api/v2.0/) in version 26.04,
requiring migration to JSON-RPC 2.0 over WebSocket.

This commit updates TrueNASCORE and TrueNASSCALE apps:
- Add TrueNASApiTrait with shared WebSocket/REST logic
- Support three API modes: auto, websocket, rest
- Auto mode tries WebSocket first with REST fallback
- Add API mode selector to config UI
- Maintain backward compatibility with older TrueNAS versions

API mapping:
- core/ping -> core.ping
- system/info -> system.info
- alert/list -> alert.list

Requires: linuxserver/Heimdall#PR (WebSocket support)
@jaycollett jaycollett mentioned this pull request Jan 29, 2026
Open
4 tasks
@mvdkleijn
Copy link
Collaborator

mvdkleijn commented Feb 2, 2026

Sorry for the delay. I was busy working on https://opencommit.eu related stuff.

I have no control over linuxserver/Heimdall so I'll leave this open and unmerged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

Issue & PR Tracker
Status: PRs

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@jaycollett @mvdkleijn