From 4835b8c7bc00a3fd05b5c20cab173b05c75e5a61 Mon Sep 17 00:00:00 2001 From: Carson Gross Date: Sat, 28 Jan 2023 19:18:22 -0700 Subject: [PATCH] edits --- www/essays/hypermedia-clients.md | 64 ++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 28 deletions(-) diff --git a/www/essays/hypermedia-clients.md b/www/essays/hypermedia-clients.md index 55f7b7fc..6503f08a 100644 --- a/www/essays/hypermedia-clients.md +++ b/www/essays/hypermedia-clients.md @@ -5,7 +5,7 @@ title: Hypermedia Clients # Hypermedia Clients -Often, when we are being pedantic and curmudgeonly in [discussions about](https://news.ycombinator.com/item?id=32141027) +Often, when we are being insufferably pedantic 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 this: @@ -25,7 +25,7 @@ say something along the lines of this: > > See? No hypermedia controls. So this JSON isn't a hypermedia, and, therefore, the API returning it isn't REST-ful. -To this, occasionally, a smart and experienced web developer will reply with something like this: +To this, occasionally, a smart and experienced web developer will reply with something along these lines: > OK, mr. REST-y pants, how about this JSON? ```json @@ -47,7 +47,7 @@ To this, occasionally, a smart and experienced web developer will reply with som } ``` > 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. +> hypermedia and, therefore, this API JSON is now REST-ful. ... @@ -55,18 +55,18 @@ One has to concede that, at least at a high-level, our online opponent has somet do appear to be hypermedia controls, and they are, in fact, in a JSON response. So, couldn't you call this JSON response 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: +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: * 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.) -And so on: the sorts of pedantic points that make technical flame wars on the internet so special. +And so on: the sorts of pedantic points that make technical flame wars on the internet such a special joy. 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 other side of the wire: the *client* that receives this JSON. +itself, but rather the other side of the wire: the *client* that receives the JSON. ## Hypermedia Clients: Important! @@ -77,8 +77,8 @@ REST-ful architectural style places on the entire system. 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. +the given hypermedia to a user. In particular, the client isn't allowed to have "out of band" knowledge about the domain +that a particular hypermedia representation, er, represents. Let's look at the proposed JSON-as-hypermedia again: @@ -106,12 +106,12 @@ language. 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. +approach to displaying things. What else could it do? -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. 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. +Now, 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, further, it is certainly not what *most* engineers would build to consume a JSON API, even if +the JSON API had hypermedia-ish controls in their responses. ## Inefficient Representations: Good @@ -121,29 +121,37 @@ have hypermedia-ish controls in their responses. _-Roy Fielding, _ 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 the presence of hypermedia controls in a hypermedia that make a hypermedia system -work, and adding them to a JSON response isn't enough. +out, it is exactly that presentation information, and the ability of the web browser (i.e. the hypermedia client) to +turn it into a UI that a human can interact with, that makes HTML work so well as a component of the larger hypermedia +system that is the web. ## 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 -the hard part, and creating a *good* hypermedia client is *the really hard part*. +entire story. And, I have come to understand, it is not really the *hard* part of the story. In fact, creating the +hypermedia *client* is the hard part, and creating a *good* hypermedia client is *the really hard part*. -We are all used to Web Browsers just being there, but think about all the technology that goes in to just parsing and -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. +We are all used to web browsers just being there, but think for a moment about all the technology that goes in to simply +parsing and rendering HTML to an end user in a normal, every day web request. It's *extremely* complicated. -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. +That's why, if we want to build web-based [hypermedia-driven applications](https://htmx.org/essays/hypermedia-driven-applications/), +we should probably use the browser: it is already an extremely powerful and well tested hypermedia client, and, +[with a bit of help](https://htmx.org/docs), it can be an even better hypermedia client. -Without that hypermedia client, Hyperview would be just another theoretical hypermedia, like the JSON above, rather +Better for most engineers to build on top of an existing hypermedia client than to try to build their own! + +That being said, there are times when building a new hypermedia client is appropriate. For example, this is what makes +a technology like [Hyperview](https://hyperview.org/) so impressive and special. Hyperview +doesn't just provide a specification for a new, mobile-friendly hypermedia, [HXML](https://hyperview.org/docs/guide_html). + +It also provides developers with a hypermedia *client* that understands how to render HXML. + +Without that hypermedia client, Hyperview would be just another hypermedia-in-theory, like the JSON above, rather than a compelling, practical and *complete* REST-ful hypermedia solution. +A hypermedia without a hypermedia client is like a fish without a bicycle, except where the fish is really only good at +bicycling. + ## Conclusion It took me a long time to appreciate how important the *client* is to a proper, REST-ful hypermedia system. This is understandable,