Using Ogen with HTMX + Templ

[PedroSoutoDev]

Hi folks, looking to get some help for a SaaS I am currently building.

Our stack is Go + HTMX with TailwindCSS and Templ.

We want to use an OpenAPI schema as the source of truth, with a schema first approach to ensure consistency in our APIs.
For this, we are using ogen, which we have set up correctly and tested, allowing us to hit endpoints. At the moment, this is all JSON, since this was mostly testing ogen as a proof of concept.

Lookign forward, we are trying to figure out the most idiomatic way to handle the fact that HTMX expects an HTML response, not JSON. With that being said, we still want to support JSON format so that we can open our API in the future, without maintaining 2 versions.

I know this may not be the best approach, but what are some ways you guys can think of doing this cleanly? I was thinking of using headers, since HTMX sets an HTXM specific header on every API requests. Using this header, we can use a middleware to parse the Response object into HTML/Templ.

I have seen this pattern mentioned before, but never with tools like ogen.
Can someone help me understand the best way to approach this, and some examples if possible?

If needed, I can also post our current structure, although we are in the early stages so its mostly a basic OpenAPI schema and a Go Web App with 3 layers (handlers, services, and repositories).

Thanks in advance for any help!

[rokf]

I have two separate OpenAPI specifications for the same app - one for the JSON API and one for the HTML (hypermedia) API, which is using templ.

The same Go executable then embeds both servers (JSON and HTML) and I've added a mux which depending on the presence of the /api prefix routes requests to the correct server instance.

// jsonServer and htmlServer are results of ogen's NewServer function.
mux := http.NewServeMux()
mux.Handle("/api/", jsonServer)
mux.Handle("/", htmlServer)

For returning HTML you can put the following into the configuration file for ogen (.ogen.yaml):

generator:
  content_type_aliases:
    text/html: "text/plain"

Then you can use that in a response like:

"200":
  description: OK
  content:
    text/html:
      schema:
        type: string

Are you sure that you'd rather have one specification with support for both HTML and JSON responses instead of separate specifications?

I haven't (yet) introduced HTMX into the equation, but if I did I'd probably try doing something like you've mentioned - reacting to the presence and content of headers HTMX is sending and eventually (optimisation) rendering only a subset of the template, initially letting HTMX do the extraction of the relevant part of the whole HTML response. I'd still keep the HTML and JSON APIs separate since they can be, I believe, (c)leaner that way, and there shouldn't be that much overhead if you keep the handler logic minimal. You've mentioned that you've already separated the implementation into multiple layers, which goes hand in hand with this 😄

[PedroSoutoDev]

Thanks for the reply!

Quick question then: Do you keep the 2 files in sync manually?

[rokf]

Kind of, but I don't keep them fully in sync. They use the same data model underneath, but they do not contain the same endpoints.

Carson described this concept well in https://htmx.org/essays/splitting-your-apis/. There'll be an overlap in query parameters, definitions, and request bodies, but the endpoints generally won't be the same. Most likely there'll also be fewer JSON endpoints as there'll be HTML endpoints, since you won't necessarily expose all of the functionality through the JSON API. It depends on your use case.

You also get to be a lot more flexible around adding and removing features from the HTML specification. With the JSON specification you'll have to make sure that you don't break things and do versioning properly, especially if you have external users of the JSON API.