# Hypermedia Systems  ## Metadata - Author: [[Carson Gross, Adam Stepinski, Deniz Akşimşek , William Talcott, and Mike Amundsen]] - Full Title: Hypermedia Systems - Category: #html ## Highlights - HTML is a hypermedia. ([Location 70](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=70)) - 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. ([Location 71](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=71)) - hypermedia servers, which present hypermedia APIs (yes, APIs) to clients over the network. ([Location 73](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=73)) - 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. ([Location 74](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=74)) - This JavaScript runtime is so powerful, in fact, that today many developers ignore the hypermedia features of the browser, in favor of building their web applications entirely in JavaScript. ([Location 79](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=79)) - Applications built in this style are not hypermedia-driven: they do not take advantage of the underlying hypermedia system of the web. ([Location 85](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=85)) - REST as a network architecture, and he contrasted it with earlier approaches to building distributed software. ([Location 95](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=95)) - We define a hypermedia system as a system that adheres to the RESTful network architecture in Fielding’s original sense of this term. ([Location 96](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=96)) - 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.” ([Location 98](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=98)) - Hypermedia-Driven Applications, or HDAs, and we contrast them with a popular style in use today, the Single Page Application. ([Location 109](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=109)) - A Hypermedia-Driven Application is an application built on top of a hypermedia system that respects and utilizes the hypermedia functionality of that underlying system. ([Location 110](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=110)) - This is a tragedy, and, frankly, a failure on the part of the thought leaders in the web development community to properly communicate and advocate for the hypermedia approach. ([Location 140](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=140)) - Hypermedia As The Engine of Application State (HATEOAS) ([Location 171](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=171)) - Hypermedia is a media, for example a text, that includes non-linear branching from one location in the media to another, via, for example, hyperlinks embedded in the media. ([Location 187](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=187)) - A hypermedia control is an element in a hypermedia that describes (or controls) some sort of interaction, often with a remote server, by encoding information about that interaction directly and completely within itself. ([Location 191](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=191)) - Because of this, we prefer the broader term hypermedia systems when describing the underlying architecture of applications built using hypertext, to emphasize the system architecture over the particular hypermedia being used. ([Location 199](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=199)) - two defining hypermedia elements (that is the two defining hypermedia controls) of HTML, the anchor tag and the form tag, ([Location 251](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=251)) - href attribute, which specifies a hypertext reference to another document or document fragment. It is this attribute that makes the anchor tag a hypermedia control. ([Location 259](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=259)) - The hypermedia server then responds to this request with a hypermedia response — the HTML — for the new page. ([Location 272](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=272)) - This may seem like a small and obvious point, but it is an absolutely crucial aspect of a truly RESTful hypermedia system: the client and server must communicate via hypermedia! ([Location 273](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=273)) - Anchor tags provide navigation between documents or resources, but don’t allow you to update those resources. That functionality falls to the form tag. ([Location 275](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=275)) - This mechanism allows the user to issue requests to update the state of resources on the server. Note that despite this new type of request the communication between client and server is still done entirely with hypermedia. ([Location 293](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=293)) - But take a step back and consider the fact that these two hypermedia controls, anchors and forms, are the only native ways for a user to interact with a server in plain HTML. ([Location 303](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=303)) - What is important, what is the crucial aspect of this JSON-based server interaction is that it is not using hypermedia. The JSON API being used here does not return a hypermedia response. There are no hyperlinks or other hypermedia-style controls in it. ([Location 340](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=340)) - tight coupling: if the format of the JSON response changes, then the code for updateUI() will almost certainly also need to be changed as well. ([Location 351](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=351)) - Single Page Application (SPA). The web application is no longer navigating between pages using hypermedia controls as was the case with links and forms. ([Location 354](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=354)) - HTML is still used to build user interfaces, but the hypermedia aspect of the two major hypermedia controls, anchors and forms, are unused. Neither tag interacts with a server via their native hypermedia mechanism. Rather, they become user interface elements that drive local interactions with the in-memory domain model via JavaScript, which is then synchronized with the server using plain data JSON APIs. ([Location 369](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=369)) - This baffling lack of progress by HTML leads immediately to the second, and perhaps more practical reason that HTML-as-hypermedia has fallen on hard times: as the interactivity and expressiveness of HTML has remained frozen, the demands of web users have continued to increase, calling for more and more interactive web applications. ([Location 413](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=413)) - These hypermedia-oriented libraries re-center hypermedia as the core technology in web applications. ([Location 435](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=435)) - “Multi-Page Application” (MPA) ([Location 438](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=438)) - MPA applications, by their nature, are Hypermedia-Driven Applications: after all, they are exactly what Roy Fielding was describing in his dissertation. ([Location 440](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=440)) - Rather than having an SPA with a bit of hypermedia around the edges, or some mix of the two approaches, you can often create a web application that is primarily or entirely hypermedia-driven, and that still satisfies the interactivity that your users require. ([Location 455](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=455)) - As you will see, htmx doesn’t need to replace entire pages, and, in fact, an htmx-based application can reside entirely within a single page. ([Location 466](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=466)) - Hypermedia-Driven Application (HDA) A web application that uses hypermedia and hypermedia exchanges as its primary mechanism for communicating with a server. ([Location 473](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=473)) - Any software project has a complexity budget, explicit or not: there is only so much complexity a given development team can tolerate and every new feature and implementation choice adds at least a bit more to the overall complexity of the system. ([Location 535](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=535)) - the job of the good software engineer is to keep complexity under control. ([Location 540](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=540)) - The sure-fire way to keep complexity down is also the hardest: say no. Pushing back on feature requests is an art and, if you can learn to do it well, making people feel like they said no, you will go far. ([Location 541](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=541)) - A hypermedia system consists of a number of components, including: A hypermedia, such as HTML. A network protocol, such as HTTP. A server that presents a hypermedia API responding to network requests with hypermedia responses. A client that properly interprets those responses. ([Location 576](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=576)) - Uniform Resource Locator A uniform resource locator is a textual string that refers to, or points to a location on a network where a resource can be retrieved from, as well as the mechanism by which the resource can be retrieved. ([Location 593](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=593)) - Here we have a relative hypermedia reference, where the protocol, host and port are implied to be that of the “current document,” that is, the same as whatever the protocol and server were to retrieve the current HTML page. ([Location 611](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=611)) - HTTP is the protocol used to transfer HTML (hypermedia) between browsers (hypermedia clients) and servers (hypermedia servers) and, as such, is the key network technology that binds the distributed hypermedia system of the web together. ([Location 618](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=618)) - The particular method being used in an HTTP request is perhaps the most important piece of information about it, after the actual resource that the request is directed at. ([Location 644](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=644)) - GET A GET request retrieves the representation of the specified resource. GET requests should not mutate data. POST A POST request submits data to the specified resource. This will often result in a mutation of state on the server. PUT A PUT request replaces the data of the specified resource. This results in a mutation of state on the server. PATCH A PATCH request replaces the data of the specified resource. This results in a mutation of state on the server. DELETE A DELETE request deletes the specified resource. This results in a mutation of state on the server. ([Location 647](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=647)) - HTTP request methods allow a client to tell a server what to do to a given resource. HTTP responses contain response codes, which tell a client what the result of the request was. ([Location 682](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=682)) - A well crafted Hypermedia-Driven Application will take advantage of both HTTP methods and HTTP response codes to create a sensible hypermedia API. ([Location 713](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=713)) - A constraint of REST (and, therefore, a feature of HTTP) is the notion of caching responses: a server can indicate to a client (as well as intermediary HTTP servers) that a given response can be cached for future requests to the same URL. ([Location 719](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=719)) - The cache behavior of an HTTP response from a server can be indicated with the Cache-Control response header. ([Location 720](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=720)) - Hypermedia clients are software that understand how to interpret a particular hypermedia, and the hypermedia controls within it, properly. The canonical example, of course, is the web browser, which understands HTML and can present it to a user to interact with. ([Location 759](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=759)) - A crucial feature of a hypermedia system is what is known as the uniform interface. ([Location 766](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=766)) - This is one reason why JSON APIs have rarely adopted hypermedia controls successfully: JSON APIs are typically consumed by code that is expecting a fixed format and that isn’t designed to be a hypermedia client. ([Location 770](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=770)) - The term “REST” comes from Roy Fielding’s PhD dissertation on the architecture of the web. ([Location 781](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=781)) - REST as a network architecture, that is, as an entirely different way to architect a distributed system. ([Location 786](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=786)) - Today, in a strange turn of events, the term “REST” is mainly associated with JSON Data APIs, rather than with HTML and hypermedia. This is extremely funny once you realize that the vast majority of JSON Data APIs aren’t RESTful, in the original sense, and, in fact, can’t be RESTful, since they aren’t using a natural hypermedia format. ([Location 790](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=790)) - Here are the constraints of REST Fielding outlines: It is a client-server architecture (section 5.1.2). It must be stateless; (section 5.1.3) that is, every request contains all information necessary to respond to that request. It must allow for caching (section 5.1.4). It must have a uniform interface (section 5.1.5). It is a layered system (section 5.1.6). Optionally, it can allow for Code-On-Demand (section 5.1.7), that is, scripting. ([Location 799](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=799)) - In practice, for many web applications today, we actually violate this constraint: it is common to establish a session cookie that acts as a unique identifier for a given user and that is sent along with every request. While this session cookie is, by itself, not stateful (it is sent with every request), it is typically used as a key to look up information stored on the server, in what is usually termed “the session.” ([Location 816](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=816)) - REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state ([Location 841](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=841)) - In a RESTful system, resources should have a unique identifier. Today the concept of Universal Resource Locators (URLs) is common, but at the time of Fielding’s writing they were still relatively new and novel. ([Location 847](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=847)) - In a RESTful system, representations of the resource are transferred between clients and servers. ([Location 853](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=853)) - The Self-Descriptive Messages constraint, combined with the next one, HATEOAS, form what we consider to be the core of the Uniform Interface, of REST and why hypermedia provides such a powerful system architecture. ([Location 858](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=858)) - So REST trades off representational efficiency for other goals. ([Location 880](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=880)) - Contrast this with the hypermedia (HTML) response. In this case, the hypermedia client (that is, the browser) needs only to know how to render the given HTML. It doesn’t need to understand what actions are available for this contact: they are simply encoded within the HTML response itself as hypermedia controls. ([Location 889](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=889)) - This difference between the two responses demonstrates the crux of REST and hypermedia, what makes them so powerful and flexible: clients (again, web browsers) don’t need to understand anything about the underlying resources being represented. ([Location 894](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=894)) - An important fact emerges from this: due to this flexibility, hypermedia APIs do not have the versioning headaches that JSON Data APIs do. ([Location 953](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=953)) - this is a deeply Hypermedia-Driven web application. Without thinking about it very much, we have been using REST, HATEOAS and all the other hypermedia concepts we discussed earlier. We would bet that this simple little contact app of ours is more RESTful than 99% of all JSON APIs ever built! ([Location 1465](https://readwise.io/to_kindle?action=open&asin=B0CC315VJK&location=1465))