itsscb/htmx
1
0
Fork 0
mirror of https://github.com/bigskysoftware/htmx.git synced 2025-09-28 13:31:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

edits

Browse Source
This commit is contained in:
Carson Gross 2023-01-28 16:07:53 -07:00
parent b0bc7bab17
commit 868166eb1a
1 changed files with 45 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
www/essays/hypermedia-clients.md
View File

@ -1,13 +1,13 @@
---
layout: layout.njk
title: Hypermedia Clients - The Missing Link
title: Hypermedia Clients
---
# Hypermedia Clients: The Missing Link
# Hypermedia Clients
Often, when we are being pedantic and curmudgeonly in [discussions about](https://news.ycombinator.com/item?id=32141027)
[REST](https://htmx.org/essays/how-did-rest-come-to-mean-the-opposite-of-rest/) & [HATEOAS](/essays/hateoas), we will
say something along the lines of:
say something along the lines of this:
> JSON isn't a hypermedia because it doesn't have hypermedia controls. Look at this JSON:
```json
@ -23,9 +23,9 @@ say something along the lines of:
}
```
>
> See? No hypermedia controls. So this JSON isn't a hypermedia, therefore the API returning it isn't REST-ful.
> See? No hypermedia controls. So this JSON isn't a hypermedia, and, therefore, the API returning it isn't REST-ful.
A smart and experienced developer will then reply with this:
To this, occasionally, a smart and experienced web developer will reply with something like this:
> OK, mr. REST-y pants, how about this JSON?
```json
@ -46,7 +46,8 @@ A smart and experienced developer will then reply with this:
}
}
```
> There, now there are hypermedia controls (normal humans call them links, btw) so this JSON is a hypermedia.
> There, now there are hypermedia controls in this response (normal humans call them links, btw) so this JSON is a
> hypermedia and, therefore, this API is REST-ful.
...
@ -57,23 +58,24 @@ REST-ful?
Well, being obstinate by nature, we still aren't willing to concede the immediate point without a
good [ackchyually](https://i.imgur.com/DpQ9YJl.png) or two:
* These links hold no information about what HTTP method to use to access them
* These links aren't a *native* part of JSON the way that, for example, anchor and form tags are with HTML
* There is a lot of missing information about the hypermedia interactions at each end point (e.g. what data needs to
* First, these links hold no information about what HTTP method to use to access them
* Secondly, these links aren't a *native* part of JSON the way that, for example, anchor and form tags are with HTML
* Third, there is a lot of missing information about the hypermedia interactions at each end point (e.g. what data needs to
go up with the request.)
All good and fine points for the pointless and pedantic technical flame wars that make the internet so special.
And so on: the sorts of pedantic points that make technical flame wars on the internet so special.
However, there is a deeper [ackchyually](https://i.imgur.com/DpQ9YJl.png) here, and one that doesn't involve the *JSON API*
itself, but rather the *client* that is interpreting the JSON.
itself, but rather the other side of the wire: the *client* that receives this JSON.
## The Missing Link: Hypermedia Clients
## Hypermedia Clients: Important!
The problem with the proposed solution above to non-REST-ful JSON APIs is that, for the JSON to participate properly in
a [hypermedia system](https://hypermedia.systems), the *client* that handles the JSON should *also* satisfy the constraints
that the REST-ful architecture places on the entire system.
The deeper problem with this proposed fix for non-REST-ful JSON APIs is that, for this JSON response to participate
properly in a [hypermedia system](https://hypermedia.systems), the *client* that consumes the JSON needs to *also*
satisfy the [constraints](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) that the
REST-ful architectural style places on the entire system.
In particular, the client needs to satisfy the [uniform interface](https://en.wikipedia.org/wiki/Representational_state_transfer#Uniform_interface)
In particular, the client needs to satisfy the [uniform interface](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5),
in which the client code knows nothing about the "shape" or details of the response beyond the ability to display
the given hypermedia to a user. In particular, it isn't allowed to have "out of band" knowledge of the domain that
a particular hypermedia representation represents.
@ -98,27 +100,34 @@ Let's look at the proposed JSON-as-hypermedia again:
}
}
```
Now a client of this API *could* simply and generically transform this into, say, some HTML, via a client-side templating
language.
A client of this API *could* simply and generically transform this JSON into, say, some HTML, via a client-side templating
language.
However, note that there isn't a lot of *presentation information* in this JSON response. A client that wanted
to satisfy the uniform interface constraint of REST wouldn't have the ability to show much more than a generic UI, since
there simply isn't much more info to go with.
However, note that there isn't a lot of *presentation information* in the JSON response: it is just some raw data about
the account and then some URLs. A client that wanted to satisfy the uniform interface constraint of REST doesn't have
much information on how to present this data to a user and would, necessarily, need to adopt a very basic "name/value"
approach to displaying things.
Mike Amundsen has written an [excellent book](https://www.oreilly.com/library/view/restful-web-clients/9781491921890/) on
how to build a proper, generic hypermedia client. But what you will see in that book is that creating a good hypermedia
client isn't trivial, and it is certainly not what *most* engineers build to consume JSON APIs, even if the JSON APIS
how to build a proper, generic hypermedia client. What you will see in that book is that creating a good hypermedia
client isn't trivial and it is certainly not what *most* engineers build to consume JSON APIs, even if the JSON APIS
have hypermedia-ish controls in their responses.
### In Praise Of Useless Information
## Inefficient Representations: Good
As an aside, a criticism of HTML is that it mixes "presentation" information with "semantic" information. But, it turns
> The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a
> standardized form rather than one which is specific to an application's needs.
_-Roy Fielding, <https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5>_
A criticism of HTML is that it mixes "presentation" information with "semantic" information. But, it turns
out, it is exactly that presentation information, and the ability of the web browser to turn it into a UI that a human
can interact with, that makes HTML work as a component of a larger hypermedia system.
At a practical level, it isn't just hypermedia controls that make a hypermedia system work!
At a practical level, it isn't just the presence of hypermedia controls in a hypermedia that make a hypermedia system
work, and adding them to a JSON response isn't enough.
## Building Hypermedia Clients: Hard
## Creating Hypermedia Clients: Hard
So just offering hypermedia controls in a JSON API response isn't enough. It is *part* of the REST story, but not the
entire story. And, I have come to understand, not the *hard* part of the story: creating the hypermedia *client* is
@ -128,18 +137,18 @@ We are all used to Web Browsers just being there, but think about all the techno
rendering HTML to an end user. We take it for granted, but it's insane. And replicating all that over again is also
insane, which is why we should probably just [use what's already there](https://htmx.org) for a lot of web development.
This is also what makes a technology like [Hyperview](https://hyperview.org/) so impressive. It doesn't just provide
a specification for a new hypermedia, [HXML](https://hyperview.org/docs/guide_html), but it also provides a hypermedia
*client* that understands HXML.
This is also what makes a technology like [Hyperview](https://hyperview.org/) so impressive and special. Hyperview
doesn't just provide a specification for a new hypermedia, [HXML](https://hyperview.org/docs/guide_html). It also
provides a hypermedia *client* that understands HXML for you to use.
Without that hypermedia client, Hyperview is just another interesting theoretical hypermedia, like the JSON above, rather
than a compelling, practical hypermedia solution.
Without that hypermedia client, Hyperview would be just another theoretical hypermedia, like the JSON above, rather
than a compelling, practical and *complete* REST-ful hypermedia solution.
## Hypermedia Clients: The Missing Link
## Conclusion
It took me a long time to appreciate just how crucial the *client* is to a hypermedia system. This is perhaps understandable,
since most of the discussion around REST was around [API Design](https://www.martinfowler.com/articles/richardsonMaturityModel.html),
and the client didn't come up much.
It took me a long time to appreciate how important the *client* is to a proper, REST-ful hypermedia system. This is understandable,
since most of the early discussion around REST was around [API Design](https://www.martinfowler.com/articles/richardsonMaturityModel.html),
and the client simply didn't come up much.
What I see now is that a lot of these discussions were putting the cart before the horse: the only way a REST-ful hypermedia
API can be useful is if it is consumed by a proper hypermedia client. Otherwise, your hypermedia controls are wasted