Why Salieno Core's API Returns HTML, Not Just JSON

The Problem with Pure JSON APIs#

Most modern software ships with a REST API that returns JSON. You call /api/v1/accounts, get back a JSON object, and your frontend framework renders it into HTML. This is the canonical approach, and it works. But for self-hosted software like a hosting control panel, it creates a hidden cost that compounds over time.

When Salieno Core's API returns a list of hosting accounts, it doesn't just return JSON. It can also return pre-rendered HTML fragments — complete, ready-to-insert markup for account tables, status badges, action menus, and form layouts. This wasn't an accident or a concession to legacy thinking. It was a deliberate architectural choice we made after watching how hosting resellers actually customize and extend their control panels.

The Customization Reality#

Hosting resellers are not frontend developers. They're sysadmins, small business owners, and agency operators who need to brand a control panel, add a few custom fields, and move on to the next thing that actually makes them money.

In a pure JSON API world, adding a custom column to the account list means:

• Understanding the frontend framework (React, Vue, Svelte, whatever the control panel uses)
• Writing a component that fetches from the API and renders the data
• Handling loading states, error states, and empty states
• Building the HTML structure for tables, cards, or whatever layout the panel uses
• Testing across breakpoints if the panel is responsive

That's a significant frontend engineering task for someone whose expertise is running servers.

With HTML-returning endpoints, the same customization might mean editing a template file that already contains the table structure, adding a new <td> with a Liquid or Go template tag, and being done. The API endpoint that powers that page already knows how to fetch the data — you're just telling it what to render.

How It Actually Works#

Salieno Core's API endpoints support content negotiation. Request application/json and you get JSON, as you'd expect. But request text/html or hit certain UI-specific endpoints, and you get server-rendered HTML fragments.

These aren't full pages. They're partials — a table body, a card grid, a form section. The main control panel shell (which is a single binary, as we've discussed before) loads once, then fetches these fragments and swaps them into the DOM as the user navigates.

This is essentially HTMX-style architecture, though we arrived at it independently based on the constraints of self-hosted software.

The key endpoints:

• /api/accounts — returns JSON for programmatic access, or an HTML table fragment for the UI
• /api/domains — same pattern, with DNS record tables or JSON arrays
• /api/billing/invoices — invoice lists as HTML cards or structured JSON

Each endpoint has a single source of truth for data access and business logic. The rendering layer is a thin template that maps the same data structure into markup.

Why Not Just Use a JavaScript Framework?#

We considered it. A React or Vue frontend with a pure JSON API is the default in 2025, and for good reason — it gives you rich interactivity, component reuse, and a massive ecosystem.

But self-hosted hosting software has constraints that SaaS products don't face:

Update cadence. When you ship a SaaS dashboard, you deploy once and every user gets the new frontend. When you ship self-hosted software, users update on their own schedule. A server-rendered HTML architecture means the frontend and backend are always in sync — there's no risk of a cached JavaScript bundle calling an API endpoint that changed shape two versions ago.

Customization without forks. If the UI is a compiled JavaScript bundle, modifying it means forking the build pipeline. If the UI is server-rendered templates, modifying it means editing a template file that survives updates (if the system supports template overrides, which Salieno Core does).

Performance on modest hardware. Hosting control panels run on the same servers that host customer sites. A 2MB JavaScript bundle is a real cost when that server is already handling hundreds of shared hosting accounts. Server-rendered HTML fragments are typically 2-15KB each, and the browser does less work to display them.

Debuggability. When something breaks, a hosting reseller can view source on the HTML fragment and see exactly what the server returned. With a JSON API and a JavaScript frontend, debugging means inspecting network requests, tracing through framework state management, and understanding a rendering pipeline that may span thousands of lines of minified code.

The Tradeoffs We Accepted#

This approach isn't free. We gave things up.

Rich client-side interactivity is harder. Drag-and-drop interfaces, real-time updates via WebSocket, and complex multi-step wizards require more JavaScript than a pure server-rendered approach typically needs. We handle this by shipping small, focused JavaScript modules for specific interactions (like the file manager or DNS record editor) while keeping the majority of the UI server-rendered.

The API is also slightly more complex to document. Every endpoint effectively has two response formats, and we need to maintain template files alongside the JSON serialization logic. It's more surface area to test.

And frankly, it's an unconventional choice in 2025. Developers joining the project expect a React frontend and a REST API. There's a learning curve to understanding why we structured things this way, even though the actual development experience (edit a template, refresh the page, see changes) is arguably simpler.

What This Means for Resellers#

If you're running Salieno Core, this architecture shows up in practical ways. You can customize your control panel's appearance by editing template files that persist across updates. You can add custom fields to account creation forms without touching JavaScript. You can build internal tools that hit the same endpoints with Accept: application/json and get structured data for automation.

The control panel feels fast because pages don't need to hydrate a JavaScript framework on load — the HTML arrives ready to display. And when something looks wrong, you can diagnose it with browser dev tools and a text editor, not a frontend build pipeline.

The Broader Pattern#

We're not alone in this thinking. The HTMX community has been making the case for hypermedia-driven architecture for years, and frameworks like Laravel Livewire, Phoenix LiveView, and Hotwire all explore similar territory. The pendulum is swinging back from "everything is a SPA" toward "server-rendered where it makes sense, client-rendered where it's necessary."

For self-hosted infrastructure software — where the operators are sysadmins, the hardware is shared, and update cycles are unpredictable — server-rendered HTML fragments paired with a JSON API isn't a compromise. It's the right tool for the job.