Why are you so wedded to JSON responses? HTMX is meant to be used to render html; my big HTMX app basically never(1) renders JSON, so much so that I have a standing instruction to coding agents that if they're rendering JSON they're probably doing something wrong. If you're attached to JSON because you're working with external API s you don't control, a good place to perform those kinds of actions is in your backend, which can then return html to your frontend
(1) the exception is I think in one place concerned a flow for uploading images, where client side requests a signed url, uploads to that url, then registers completion. Getting the signed url back is JSON meant for the uploader
I want to handle a JSON response because I usually return data for multiple page elements. These aren't external APIs, they're requests to the backend server.
A simple example is adding a note to a product or order. When you submit it, it gets inlined, and say a visual note counter is incremented. Usually I'll return multiple HTML fragments if it's convenient, but I'll return a data structure if needed.
But now I want to add a JSON API to the program: I could reuse the same routes (/create, etc), but require an application+json header; or add a full /api/ component essentially duplicating the logic from the main app.
Fat services, thin routes. Try moving your business logic to a library and consume it from both your UI and API routes. That minimizes duplication and decouples your public API resolvers (with backwards compatibility requirements etc) from your private UI resolvers (which you want to evolve rapidly to optimize your UIX).
That's what we did and it works pretty well in practice.
As a result for POST requests you have to have htmx routes that accept urlencode and API routes that accept JSON, and JSON is far superior. But for outputs I actually think separating your UI and API is helpful. The code reuse is not worth the entanglement of concerns.
It's a service, and I want to add a CLI for humans and agents. Aeolos' reply makes a lot of sense, I can refactor the backend into a library and add thin UI and API routes on top of it.
I'd assume because of the conception that json = data. Html = presentation. But if you just use barebones html, this could work very well. Just add a wrapper in the api to return json as html to try it out a bit.
(1) the exception is I think in one place concerned a flow for uploading images, where client side requests a signed url, uploads to that url, then registers completion. Getting the signed url back is JSON meant for the uploader