Hypermedia Clients

https://htmx.org/essays/splitting-your-apis/

We went on a wild goose chase trying to recreate a hypermedia client with javascript, contorting xmlhttprequest from an application api into a data api, on an already existing hypermedia client (the browser) because the latter stagnated and failed to fill out its functionality.

htmx adds the missing functionality to make the browser a functional hypermedia client.

The downside to this boost in productivity is when the need for a mobile app comes along, now you need a non-REST API, too. Then you can take out GraphQL or gRPC or something suited for the task. Your mobile client would most likely be using a different surface of the API even if you had one for web clients, so it’s not like you’re wasting much effort here.

Yeah, once I realized this, HATEOAS / "strict" REST immediately went into my "nope" bucket. It's pretty much fine for humans and makes some compelling decisions in that context, but it's wildly unusable and unstructured for literally anything else and that makes it almost useless.

HTTP verbs and codes are plenty useful, and REST has been co-opted to mean "use verbs and codes correctly" and... I'm OK with that. It summarizes as "follow the patterns that much of the computing world relies on, so you don't break shit everywhere all the time" and that's something absolutely worth understanding and adopting in depth.

That's the point I've never understood, and maybe someone here can clear it up for me?

As far as I understand, Fielding is constantly hammering on the point that navigation between resources should be hypertext-driven, so no "extraneous" information (where some resource or method is located) should be used. Only hypertext-style links from query/response to query/response.

But HTTP has very generic verbs. GET, PUT etc. They don't mean much.

Okay, REST proponents will say, while Fielding did his work in the context of HTTP, but envisioned a much richer hypertext capability.

Good. Now I have verbs like "Resize photo" or "Follow user" or "Get GPS coordinates from EXIF" in my hypertext API? How is a generic client supposed to understand those?

That's where I'm stuck. What's the use of it all if the client still needs to know everything about the domain (unavoidably, IMO)? Showing responses to the user and having him decide cannot be a real proposal, can it?

It’s the foundation of the World-Wide Web, which is the most successful platform in history. It solves a tonne of problems, that’s why it is so successful. You are using HATEOAS right now.

https://hyperview.org/ should be held up really high to show what’s possible if we think outside of the browser. It looks like it’s optimized for Material UIs, but we can imagine what it might look like for other UIs like Apple, etc.

Apple has given us a glimpse of that with Apple TV Markup https://developer.apple.com/documentation/tvml. While it’s not a hypermedia client, it does show us what UIs are possible via markup.

https://native.live/ is another glimpse, though the financier of this project has said on Twitter that his company is strongly incentivized to keep it “Elixir only”, so I’m not sure where it puts that project with respect to a SwiftUI hypermedia client.

These sorts of domains are pretty uncommon. It's far more than just an extra layer of indirection to keep backwards compatibility; in practice, you can't change HTTP-layer APIs regardless of your hypermedia controls. People bookmark things and write curl scripts.

- It can be a much simpler approach to building an application. As evidence for this fact, consider Contexte's experience moving from react to htmx for their Saas application: https://htmx.org/essays/a-real-world-react-to-htmx-port/. They reduced their codebase to 1/3rd the size with no reduction in UX, dropped JS dependencies by 95%, etc. Not every project is this amenable to hypermedia, but many are.

- Related to this, hypermedia is the "native" architecture of the web, and browsers have a lot of technology built into them for it. htmx is a depenedency-free 12k library because it builds on top of that model.

- By adopting hypermedia as your system architecture, you push your logic back onto the server side, where you are free to use whatever programming language you prefer: clojure, python, haskell, etc. This lets you write more code in your preferred programming language and execution environment.

- The server side is a trusted computing environment, so you can have complete access to a data store when writing logic there. This is in contrast with the browser, where you can't have unrestricted access to the data store due to the fact that a hostile user can open a console and start manipulating the data store. On the server side, you can just use SQL. On the client side, you can't, without putting your whole data store at risk.

There are certainly tradeoffs associated with the hypermedia approach: it doesn't work well in situations when you need to respond quickly to many UI-driven events, it sacrifices representational efficiency for flexibility, etc. There isn't a silver bullet, after all.

With htmx I am trying to expand the set of applications for which the hypermedia approach will work, but I have no illusions that it will work for everyone: nothing is right for everything.

If you (and only you, personally) control both the client and the server (and by "control" I mean you can update/deploy them as you please, simultaneously if necessary), you can feel free to use any sort of homebrew efficient binary stateful protocol and format you like, with no consequence.

However, the more parties that are involved (co-workers, separate teams, external organizations, etc.), and the less those parties are able/willing to synchronize their efforts over time, the more benefit you will see from aspects of REST and HATEOAS.

Most developers aren't working in a domain and environment where the diversity of stakeholders is maximally broad for both the client(s) and server(s), so "going full HATEOAS" is often overkill, but you should still understand it, in the same way that you need to understand why data schemas ideally conform to fourth normal form, even if your production data is denormalized in practice.

While some benefits from some REST practices can start accruing even in the single developer situation, simply because there can be costs to coordinating between present-you and various versions of past-you and future-you, and their respective client and server deployments, that only makes a case for partial adoption. By all means, only use the practices and patterns that make sense and solve or avoid a pain point for you in your situation rather than being dogmatic.

In that sense, REST and HATEOAS shouldn't be considered in any different light than other aspects of writing software such as external dependencies, or changing the toolchain, or splitting some code into its own library or module, or publishing code as open source; sometimes it makes sense, sometimes not (especially when the costs are concrete and the benefits hypothetical).

I find it difficult to take it seriously because the people making it do not acknowledge any of the history that has led them to this point.

They are in a point where they can say that the architecture that underpins the web does not solve their current problems because they are building things on top of that solution.

For a lot of people the OS is a wrapper for the browser and that's it. We could reasonably say for those people the OS does not solve any of their problems, except for the fact that it exists to enable them to have a browser and go to the few places they go to.

HATEOAS doesn't solve many developer's problems in the same way because those problems are enabled by sitting on top of the solution that is HATEOAS.

Also I can't remember who it was that said it, it was back in the time when people were arguing about SOAP vs. REST which, well whatever, I think it might have been Tim Bray or Paul Prescod and they said in discussing what was needed to build a world wide network for information sharing they were predisposed to accept the arguments of the people who had actually done such a thing.