Difficulty understanding the book's definition of "hypermedia system" (see: "Introduction - What is a Hypermedia System?")

[AleksandrHovhannisyan]

Hello,

Thank you for publishing this book for free! I just wanted to offer some feedback on an introductory section that I found confusing as someone who hadn't heard the term hypermedia before. The section reads (emphasis, in bold and italics, is my own):

To understand what a hypermedia system is we’ll first take an in-depth look at the canonical hypermedia system: the World Wide Web. Roy Fielding, an engineer who helped create specifications and build the implementations of many early pieces of the web, gave us the term REpresentational State Transfer, or REST. In his PhD dissertation he described REST as a network architecture, and he contrasted it with earlier approaches to building distributed software.

We define a hypermedia system as a system that adheres to the RESTful network architecture in Fielding’s original sense of this term.

Unfortunately, today, you probably associate the term “REST” with JSON APIs, since that is where the term is typically used in industry. This is a misapplied use of the term REST because JSON is not a natural hypermedia due to the absence of hypermedia controls. The exchange of hypermedia is an explicit requirement for a system to be considered “RESTful.” It is a long story how we got here, using the term REST so incorrectly, and we will go into the details later in this book. But, for now, if you think REST implies JSON, please try to set that understanding aside while reading this book, and come to the concept with fresh eyes.

It is important to understand that, in his dissertation, Fielding was describing The World Wide Web as it existed in the late 1990s. The web, at that point, was simply web browsers exchanging hypermedia. That system, with its simple links and forms, was what Fielding was calling RESTful.

JSON APIs were a decade away from becoming a common tool in web development: REST was about hypermedia and the 1.0 version of the web.

The main reason I find this confusing is because the book has not yet defined "hypermedia" in concrete terms—are we talking about media as in images, videos, audio, fonts, and other resources that HTML uses and that servers can host and send to clients? Or is the "media" in "hypermedia" something entirely different?

The prior section reads:

What do you mean hypermedia systems?

Well, yes, HTML is a hypermedia. But there is more to the way the web works than just HTML: HTTP, the Hyper Text Transfer Protocol, is what transfers HTML from servers to clients, and there are many details and features associated with it: caching, various headers, response codes, and so forth.

And then, of course, there are hypermedia servers, which present hypermedia APIs (yes, APIs) to clients over the network.

And, finally, there is the all-important hypermedia client: a software client that understands how to render a hypermedia response intelligibly to a human, so that a human can interact with the remote system. The most widely known and used hypermedia clients are, of course, web browsers.

All of these feel like very loosely defined terms, with no concrete examples. The book says HTML is a hypermedia, but then it introduces the term hypermedia server and circularly defines it to be "a server that presents a hypermedia API." I walked away from this feeling like there's some prerequisite knowledge I don't yet have.

Second, I don't think this section does a good job of defining either Fielding's definition of the term "hypermedia" or the book's definition. My only takeaway from this section ends up being that "REST isn't just about JSON."

I think adding some examples would be helpful.