Hypermedia Systems | Hacker News Reader

Hypermedia Systems

hypermedia.systems

136 pointszdw34 comments

Hi all.

This is a book that was in contract to be published but the publisher pulled out, so we are going to try to self publish it (never done this before, we'll see how it goes.)

It is in somewhat rough shape because we are redoing the book with a more conceptual bend than the publisher wanted: there are some repetitive sections due to re-arranging, typos and areas that need to be expanded, but the rough outline is about what we want and much of the content is pretty solid.

The book looks at hypermedia conceptually, then htmx for hypermedia-driven web applications, then HyperView for hypermedia-driven mobile applications.

We the authors all agreed to keep the online version available for free forever.

Hope people find it useful and interesting.

Not sure if there's a better way to contact you, but it looks like all the "Next part"/"Previous part" links on the part pages are broken. e.g. https://hypermedia.systems/book/part/hypermedia-concepts/ links to https://hypermedia.systems/book/part/2, which 404s. It should actually link to https://hypermedia.systems/book/part/htmx/.

thank you, we are writing a custom transform of the asciidoc source to a website so there are some broken aspects

>but the publisher pulled out

Can you share why? Did they think the topic was niche?

Looks like it.

From htmx’s twitter:

> the book was initially in contract w/ a tech publisher, but was dropped because they didn't feel there was a big enough market

yep: not enough of a market, which is probably true at this point

we were straining to make the book fit into what the publisher wanted, so this gives us a good opportunity to write the book that we want

I wrote a master thesis on this in 2018 [1]. It's about hypermedia. I did it on a system called XIMPEL (an XML-based hypermedia system).

Do I find my thesis particularly brilliant? No. More like, cute, some fun musings.

But this topic is really niche and my thesis exactly fills that spot. So it might be interesting to some.

Also, the history section with Vannevar Bush is a must read (not per se in my thesis, just in general). I also saw that this submission had Vannevar Bush mentioned, reading about the Memex is such a cool thing if you think about in what time this was written.

[1] https://melvinroest.github.io/ximpel/

I’m curious about it but when clicking on the link to “Documentation” I got 404’ed by GitHub with a push to “read the full documentation”.

I had better luck at ximpel.net, taking a look at it now.

An important topic I do not see discussed on HTMX and other such tools is testing.

Frontend frameworks all have a way to unit- and integration-test their components without resorting to Cypress or Playwright. How do you integration-test the effect of your hypermedia enhanced applications without a (headless) browser? Using Chrome for a few end-to-end tests is fine. But it is not a replacement for in process RackTest (to give a Rails specific example).

From a quick glance testing is not addressed in this book either.

You can write tests just like you would test a JSON API. But instead of testing the JSON structure, you can test the HTML structure. Depending on how deep you want to go, you can parse the HTML response and check for the components, but sometimes just checking for bare strings is enough. For example, taking the FastAPI testing docs[0], instead of:

  assert response.json() == {"detail": "Item already exists"}

You can write:

  assert f"<b>Item already exists</b>" in response.render().decode()

One thing I found using HTMX (or just HTML) is that the apps are less fragile. I know that if I return a chunk of HTML, the browser will render it the same way every time. With a JSON-based SPA, maybe that chunk of JSON ends up triggering multiple side effects, re-renders, etc. which can behave differently depending on the current application state. This all affects the amount of testing that I feel comfortable with.

[0]: https://fastapi.tiangolo.com/tutorial/testing/?h=testing#ext...

If I was to test things that were part of UI code, but were still "mechanical" enough to test automatically, I would throw responses into an HTML parser to make sure I'm presenting the right data. (In a way, HTML strings are also a kind of "virtual DOM")! If you need to test interactions though, I don't think a headless browser is avoidable.

I would think that because HTMX == less JavaScript that there’s less of a need to test functionality. And the testing that remains will need a browser to be tested. Complex logic will still be written in JavaScript so then one can use regular JS testing tools again.

We do not test because of a language used but because there are assumptions expressed in code. “Clicking a button validates the email address” is a test you need to have regardless of if it’s implemented as `hx-get` or `onSubmit`. I would argue having good test coverage for the former is more important because the action happens further (another controller+template instead of the same React component).

Yeah I wasn’t expressing myself clearly, let me try again.

HTMX writes quite a bit of the logic for us. We don’t need to test that logic because we can assume that it’s been tested. We only need to test the remaining logic, of which there is less and it’s less messy because it’s more declarative (if I understand HTMX).

If we use an input of type “email” we also don’t test if its validation works.

This book coming out is an amazing news. The HTMX website already does a fine job of explaining the philosophy behind hypermedia applications. But taking a 101/102 application like contacts app and building it with hypermedia is enlightening. Wishing you best luck for this book. I also liked the fact that rather than preaching one way to do things, the book shows alternatives and their downsides too (for example, the scripting chapter covers vanilla javascript, alpine.js and hyperscript). Kudos!

I lead tech for a 30-person startup doing ~10m/yr revenue. We are about to embark on a rebuild because things are breaking now - and I have been on a charm campaign to build it with HTMX. Development was outsourced before I came and we ended up with SPA and microservices galore. 10 repos, 5 development languages, 4 lambda functions - text-book JS fatigue.

If I make it happen, the rebuild with HTMX should be a lot of fun!!

I understand htmx is a front-end framework... What will you use for the rest of the stack?

Django monolith. Our essential function is to ingest tons of health-care payer and clinical data and give out insights.

We have opened up the repo for the book if people want to submit feedback there:

https://github.com/bigskysoftware/hypermedia-systems

A recent talk about this by Carson Gross: https://youtu.be/LRrrxQXWdhI

The book segment header links (in italic [0]) serve raw html which is probably not the intention (unless its an exercise for the reader that I've missed in my quickscan :-)

The section on mobile clients seems very timely. At least one fediverse server [1] is adopting elements of htmx and it would seem that the corresponding clients would be a canonical example using this technology.

[0] https://hypermedia.systems/book/part/htmx

[1] https://github.com/jointakahe/takahe

> The book segment header links (in italic [0]) serve raw html

Fixed! (It worked fine in the dev server...)

I see two large unanswered questions here.

1. The approach is about grafting pieces of HTML inside a htmx-enabled HTML document. These pieces may also contain arbitrary htmx. This may lead to an explosion of possible states. What approaches and tools are offered to manage this explosion, and prevent states that don't make sense? (In the SPA world, things like React and Svelte do that.)

2. The approach forms an ever-changing HTML document. Most often you want such a document to match some server-controlled state. What approaches are suggested to make sure things are in sync? (Say, React can just completely re-render the logical state, only updating parts on the screen which need a visual update.) Classic HTTP and HTML are all about serving static files, even.when following links (GETs should be idempotent); this approach has no such limitations / guarantees.

1. The best way to avoid creating an explosion of states is [Locality of Behavior]. Elements should avoid targeting other elements that are not inside them, especially those written in different templates. Sometimes this is unavoidable (i.e. updating a site-wide shopping cart). If htmx is adopted widely and those state explosions become an issue (I'm not aware of it happening so far), maybe a "redux for htmx" will be invented. 2. "Classic HTTP and HTML are all about serving static files," I'm not sure about that. In my opinion, dynamically generated responses are a core part of HTTP. All HTML and all the htmx attributes are sent by the server, so we're only keeping the server in sync with itself. I get what you mean though. Going back to the shopping cart example, the code that adds an item to the cart needs to remember that the cart total is displayed in the nav bar and include that fragment. A server mechanism could possibly be created that tracks these dependencies, but again, it's not been an issue yet.

One topic I haven’t seen discussed yet is that an SPA style web app doesn’t just have JSON-API endpoints for itself but also for external systems, like an iOS app. When using HTMX or similar systems you’d have to create 2 end points for a certain bit of functionality: one that sends HTML and another that sends JSON.

After browsing the book: they do touch upon this and their take is that these are 2 different things with different requirements and should be built relatively separately: https://hypermedia.systems/book/json-data-apis/

That makes sense to me...

I do think there would often be significant common parts between an htmx endpoint and json data endpoint, so to me it makes sense to implement these in a way where they can share common code or be built on a common layer.

Using Java microservices I have only a single endpoint per use case that returns different representations based on what is requested by the user agent. If its a browser it will request HTML and I use some simple Mustache libraries to format the HTML output. If json is requested then the built in json serialized does its thing. It feels quite elegant. I think there's room for some kind of automatic HTML serializer as well. Where styling can then be done directly in CSS.

Might be able to do this with a relatively simple header based middle ware which alternatively returns html or just the data injected into the view

This can be done quite easily via the Content-Type header.

This kind of content negotiation is exactly what REST and hypermedia were intended to handle gracefully.

I read "Enhancing web applications without using SPA frameworks" just below the URL to "Hyperview" - which needs React Native to run. Am I the only one detecting heavy cognitive dissonance here?

Nope: the web application bit is based on htmx, which is a stand-alone JS library.

To build a mobile hypermedia client (which is what Hyperview is) is a massive effort and building it on top of something like React Native makes a lot of sense. What matters isn't the underlying implementation details, but rather the hypermedia system (client, hypermedia format, etc.) that HyperView gives you.

Hyperview only uses React Native for its cross-platform widgets. (I wish Flutter had been used instead). You don't need to touch it unless you're writing custom elements.

Reply on news.ycombinator.com