Introduction
When I first started building ha-glinet, the roadmap was driven by what the router could physically do for my smart home—things like sending SMS alerts, toggling VPNs, and tracking connected devices.
But as the integration grew to cover more modules and versions of GL.iNet’s 4.x firmware, a completely different challenge emerged. I wasn’t just writing Home Assistant code anymore; I was constantly translating, testing, and debugging GL.iNet’s underlying JSON-RPC architecture.
To scale the project without breaking my own sanity, I needed a dedicated environment to test API payloads, map router behaviors, and catch breaking firmware changes before they hit users.
That is why I built the API Playground feature.
What the API Playground Is
The API Playground is an internal developer sandbox and diagnostics cockpit built directly into the integration.
Instead of forcing you to guess whether a specific API call will work, the Playground provides a safe, interactive interface inside the development environment to execute live or mocked Remote Procedure Calls (RPC) directly to the router. It bridges the gap between raw router firmware and Home Assistant’s front-end configuration flow.
1. Taming the Hidden JSON-RPC Architecture
One of the core realities of modern GL.iNet firmware is that it doesn’t use standard, predictable HTTP REST endpoints (like querying /api/wifi/status). Instead, everything runs through a unified, unpublicised JSON-RPC interface.
Every single request—whether you are scanning for Wi-Fi networks or checking a WireGuard tunnel—has to be wrapped in a specific JSON structure and pushed to a single endpoint. The API Playground was built to handle this exact blueprint:
$$\text{Request} = \{ \text{“jsonrpc”}: \text{“2.0”}, \text{“method”}: \text{“call”}, \text{“params”}: [ \text{sid}, \text{module}, \text{action}, \text{args} ], \text{“id”}: 1 \}$$
The Playground lets me manually drop in the module, the action, and the args, handling the heavy lifting of injecting the active session ID (sid) automatically. It turns what used to be a tedious process of using external API clients into a streamlined, one-click test inside the project workspace.
2. A Safety Net for Complex Router States
Testing network routing code on a live, production home network is inherently stressful. If a script stalls while trying to parse a wireless repeater state, you risk dropping the connection entirely.
The API Playground acts as a literal buffer. I can safely probe complex, fast-moving parameters—like checking if the router returns RepeaterState.CONNECTED or monitoring dynamic DFS channel availability—without risking the stability of the core Home Assistant entities. If the router returns a malformed payload or an unexpected error, it gracefully displays in the Playground console rather than causing the integration setup flow to crash.
3. Catching Firmware Quirks Before Users Do
GL.iNet routers vary wildly across models. A GL-MT3000 (Beryl AX) behaves differently than a GL-X3000 (Spitz AX) with a built-in cellular modem.
When a new firmware update drops, the API Playground is the first line of defense. It allows for quick “smoke testing” of the API endpoints to see if the manufacturing team moved the furniture around in the backend. If an argument type changes from a string to an integer in a new version, the Playground exposes it instantly, allowing me to update the ha-glinet core logic long before it affects anyone’s daily automations.
Unintended benefits from the API Playground
1. For user edge cases, they do not need to wait for me to create functionality. In most cases they will be able to replicate the functionality via Home Assistant automations.
2. Debugging user issues raised on GitHub became a lot simpler. When in doubt. I can get them to enable the feature and provide me with the response for any problem method and know exactly why the integration is failing for them.
3. Having the ability to submit a request and interpret the response directly in home assistant means automations can take advantage of this to perform tasks directly via code rather than fumbling with sensors and toggles.
Lessons from the Playground
Building a testing playground taught me a few distinct lessons:
- UI tools aren’t just for end-users: Having a clean visual interface for debugging saves hours of command-line sniffing.
- RPC requires strict validation: Because JSON-RPC fields are deeply nested, catching malformed parameters early prevents cascading errors in Home Assistant.
- Developer tooling pays dividends: Spending the extra time to build a sandbox early made writing features and debugging user issues significantly simpler.
Closing Thoughts
The API Playground started as a personal tool. I simply needed a faster, safer way to interact with GL.iNet’s challenge-response authentication and unified RPC endpoint without constantly restarting my Home Assistant instance and needing to be present on the same network as the router.
Today, it serves as the foundation that keeps ha-glinet stable as the integration continues nearing 500 active installations. It ensures that as the community grows and more router models are introduced, the integration can adapt softly, predictably, and cleanly.
It keeps the development process exactly how I like my releases to be: reassuringly boring.
Worthwhile Mentions
- ha-glinet is officially onboarded into HACS. Home Assistants custom integration repository!
- Gl.iNet’s 4.9.0 firmware has some breaking changes. Seeing how its slowly being released into stable for multiple devices. I’ll be looking at how other similar projects normally supports transitions like this while retaining backwards compatibility