These diverse types of interlinked, nonlinearly accessed media forms are called hypermedia. As software architect Irakli Nadareishvili explains, “Hypermedia is the matter of which the World Wide Web is made. Much like the physical world is built of interacting elementary particles (Bosons and Fermions), the web is essentially a universe of myriad interacting hypermedia documents.” The more common term hypertext is closely related to hypermedia, with the bulk of the Web consisting of webpages primarily written in Hypertext Markup Language (HTML). But hypermedia transcends hypertext, the word suggesting that more than just text is capable of being hyperlinked, such as graphics, videos, and music files.
In essence, then, hypermedia is just another name for everything that we see, hear, and interact with on the Web. But since the early 1990s, the general concept of hypermedia has been largely superseded in popular usage by the term “interactive multimedia.” It is primarily only in the world of software engineering and architecture that people continue to speak of hypermedia. And these days, the term is most often used in the context of developing Web-based Application Programming Interfaces, or APIs.
As the complexity of software applications and systems continues to grow, there’s an increasing need for different components within a single application—and for entirely separate applications—to be able to communicate with each other simply and clearly. This cross-linguistic data-exchange is what APIs have always been used for, but the variety of APIs and the languages used to code them can vary as widely and be as idiosyncratic as individual software applications themselves. An API developed by Facebook and an API developed by Twitter may not communicate nicely with each other, and developers usually have to sort through any given API’s unique documentation to figure out how to use it with their own application. Many system engineers and software developers believe their jobs would be far simpler if there existed a common format for writing APIs, following a shared, agreed-upon structure. And they look to the Web as a proven example of such a possibility.
The Web is a system of hyperlinked hypermedia that, despite the endless varieties of software languages that are used to construct its websites and media types, generally manages to stay remarkably interconnected and communicate clearly between its many constituent parts. A single hyperlink, clicked within a Web browser, can serve up a YouTube video just as easily as it can display a BuzzFeed text-and-gif listicle. This has led a number of thoughtful software architects to furrow their brows and wonder if there isn’t a better way to go about creating APIs. Why not focus our efforts on designing hypermedia APIs, they ask, that can be just as simple and universally understood as the Web’s hyperlinks are by virtue of using the inherent power of hyperlinks themselves?
Why not, indeed?
Build and Design your APIs Now with SwaggerHub
A Brief History of Hypermedia
But before we get into the world of user-friendly APIs that hypermedia makes possible, a little context seems in order. Where did the concept of hypermedia come from? And how does it relate to the idea of hypermedia APIs?
To cut a long story short, credit for the original concept of hyperlinks and hypermedia typically goes to the renowned 20th-century American engineer Vannevar Bush, whose 1945 essay in The Atlantic, “As We May Think,” expounded his idea of the “memex,” a mechanical desktop information-retrieval tool that would permit its users to quickly index and access vast stores of information by nonlinear association. Bush’s vision effectively describes the nonsequential browsing and hyperlinking functionality that we now associate with the Web, and his prophetic essay continues to be read by computer-science students around the world. But it wasn’t until nearly two decades later, in 1963, that the actual words “hypertext” and “hypermedia” appear to have first been coined.
Inspired by Bush’s essay, a visionary IT engineer named Ted Nelson began using these terms in his work and finally published them in his 1965 article, “Complex Information Processing: A File Structure for the Complex, the Changing and the Indeterminate.” He wrote, “Systems of paper have grave limitations for either organizing or presenting ideas…. However, with the computer-driven display and mass memory, it has become possible to create a new, readable medium, for education and enjoyment…. Let me introduce the word ‘hypertext’ to mean a body of written or pictorial material interconnected in such a complex way that it could not conveniently be presented or represented on paper.”
Three years later, at the famous “Mother of All Demos” of December 9, 1968, computer engineer Douglas Engelbart demonstrated a working computer system featuring all the trappings of what we expect in personal computers today—including a navigational mouse, a graphical user interface (GUI), multiple application windows, and clickable hypertext links. On that day in San Francisco, Bush’s and Nelson’s vision of networked hypermedia was visibly, demonstrably born.
Fast-forward to December 1990, when Tim Berners-Lee, a year after outlining his “WorldWideWeb (W3)” project, successfully transmitted data over the internet via his Hypertext Transfer Protocol (HTTP), accessing multiple documents composed of his HTML code through hypertext links. “HyperText,” he explained in 1992, “is a way to link and access information of various kinds as a web of nodes in which the user can browse at will.”
By the year 2000, the Web woven by Berners-Lee had truly encompassed the world, and one of its leading pioneers, Roy Fielding—who helped author the initial HTTP specification that Berners-Lee had begun—was busy completing his doctoral dissertation at the University of California, Irvine. In Chapter 5 of his thesis, Fielding coined a term that continues to resound today in all discussions of Web services and APIs. That term is “REST,” which stands for Representational State Transfer. Fielding conceived of REST as a way of defining the architectural style and structure of “distributed hypermedia systems” in general and the World Wide Web in particular. In his words, “REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.” It is, in other words, a meta-view of the way that the Web—and HTTP—works. Many (but not all) APIs relying heavily on HTTP can be considered “RESTful,” and REST is typically used as an alternative style in which to read and write Web services and APIs, alongside programming standards such as SOAP (Simple Object Access Protocol), WSDL (Web Services Description Language), and RPC (Remote Procedure Call). Most significantly, because REST APIs almost always use HTTP syntax—including the verbs GET, PUT, POST, etc.—they are widely considered to be the definitive form of hypermedia APIs.
Some believe that the rapidly emerging varieties of hypermedia systems, however, transcend even REST. In his 2012 book Building Hypermedia APIs with HTML5 and Node, author Mike Amundsen writes, “It is true that REST identifies hypermedia as an important aspect of the style, but this is not the case for the inverse. Increasing attention to hypermedia designs can improve the quality and functionality of many styles of distributed network architecture including REST.”
While the details of what, exactly, constitutes hypermedia systems and hypermedia APIs remain subject to debate, one thing is clear: Because every architect of Web APIs understands the universality of HTTP, at least in theory, then the simplicity, flexibility, extensibility, and potential universality of HTTP-based APIs should be readily apparent.
And some HTTP-based APIs are more RESTful than others, adhering to the hyperlinking protocols and client-server-independencies that define REST constraints more carefully than others (such as the constraints of HATEOAS, or Hypermedia as the Engine of Application State, which specifies the ways in which hypermedia clients can evolve independently of servers by only communicating data in terms of hypermedia itself). The field of hypermedia APIs is very much still in a state of evolution, subject to competing interpretations and confusion, and is being actively and ongoingly redefined.
Understanding Hypermedia APIs
In the second decade of the 21st century, the rise of cloud-based, SaaS applications, mobile apps, and social networking sites is driving the growing interest in RESTful, hypermedia APIs at an accelerating rate. Applications need to communicate with each other more fluidly than ever before, and developers need a way of knowing more easily what options are available to them when they interface with others’ APIs. One of the key benefits of using hypermedia as opposed to traditional XML-based APIs is that, in addition to providing common parameters for all developers to code within, the server hosting a hypermedia API can also generate a complete list of options (or link relations) available to the client, which can then be easily, unambiguously called upon in future HTTP requests.
An example used by Mike Amundsen demonstrates the fields of information that one machine-readable server response, written in the hypermedia language Siren, might provide—enabling a client to know exactly what data parameters are available to modify or otherwise engage with through an HTTP call following the link “http://example.org/customers/123,” which returns:
"actions": [
{
"name":"update-customer",
"title":"Update Customer",
"method":"POST",
"href":"http://example.org/customers/123",
"type":"application/x-www-form-urlencoded",
"fields": [
{"name":"status","type":"hidden","value":"partial"},
{"name":"return","type":"hidden","value":"full"},
{"name":"email","type":"text" },
{"name":"sms","type":"number" }
]
}
]
“Now,” notes Amundsen, “you can see lots of information about what this URL represents, what you can do with it, and what’s at the other end of the link. That’s hypermedia.”
Siren is just one of a number of new languages being used to develop standards for APIs written in hypermedia-friendly terms. Others include HAL, JSON API, JSON-LD, XHTML, Hydra, Collection+JSON, and UBER, with more no doubt waiting in the wings of GitHub, their developers hoping that more people will use them. What all of them have in common, though, is a reliance on URLs (and URIs) and the HTTP protocol to get their API links and data modifications across to a server, and then pull data from the server back to a client. Unlike more traditional SOAP APIs, which usually use HTTP (or even SMTP) only as a way of “tunneling” from one place to another over the internet, hypermedia APIs speak the language of, and live entirely within, the HTTP protocol itself. Perhaps more than any other format, hypermedia APIs put the “Web” in Web APIs, but they’re still relatively new and therefore far less commonly found in Web-based applications than earlier APIs.
In his book on Hypermedia APIs, Amundsen identifies nine distinguishing criteria of hypermedia that he calls “H-Factors,” divided into five Link Factors and four Control Factors:
The five link factors denote specific linking interactions between client and server: Outbound, Embedded, Templated, Idempotent, and Non-Idempotent. The remaining four control factors provide support for customizing metadata details (e.g. HTTP Headers) of the hypermedia interaction: Reads, Updates, Method, and Link Annotations.
No widely used hypermedia design, he explains, currently employs all nine factors in its implementation. However, each of the factors can be an important building block in developing hypermedia, and some of these hypermedia affordances overlap with what’s been called the Richardson Maturity Model, as developed by RESTful API expert Leonard Richardson. But in any case, the overall point that Amundsen’s and Richardson’s criteria both make clear is that hypermedia is, fundamentally, just a way of being able to put links into your API resources that a client can follow, in order to represent and modify data and interactions between your resources. That is, the prevalence of hyperlinks signifies hypermedia, but only when an array of new linking possibilities is part of the API response that a server returns. Otherwise, a hyperlink on its own is likely just a lone hyperlink, not hypermedia.
But considering real use-cases always helps, and perhaps the most well-known and popularized examples of a hypermedia API is the Public Media Platform (PMP) developed by NPR and its partner news organizations. The goal of the PMP was to provide a universal news resource that all other radio stations and news organizations would eventually be able to read, pull content from, and contribute to, creating a journalistic repository the likes of which had never been seen before. But the challenge it posed to the project’s lead developer, Irakli Nadareishvili, was immediately apparent: How could he create a single, cross-organizational platform that vastly different websites, mobile apps, and databases could all successfully communicate with and understand? The answer, he says, became evident when he and his team decided to use hypermedia and the “religious usage of URLs for referencing everything (even internally).” This broke the biggest limitation of traditional APIs, he noted, which is the silo-ing of content. As he explained it:
In “classical” APIs: all documents need to live within the API itself. It’s not like Twitter API can make sense of a tweet that was created and is stored in another API. But PMP can, because all of its content are just URLs to certain types of documents. Where these documents live is largely irrelevant.
I repeat: you can have core data that your API relies on live somewhere else, as far as you can reference it!
That is groundbreaking in the APIs world. But ironically it’s natural for the rest of the web. You don’t save your page directly into Google’s database to make it searchable. And you don’t have to publish your webpage into somebody else’s database to make linkages. You kind of had to do such silly things for the APIs, though. But now we don’t need to anymore.
The PMP is just one of a number of high-profile implementations of hypermedia that is proving the efficacy of the model, both in theory and in practice. PayPal, Amazon, and FoxyCart are also ahead of the curve, expanding their accessibility and versatility through the use of hypermedia APIs, and more are sure to follow their lead in the coming months and years.
The Future of Hypermedia
As system architectures become increasingly complex, the need for a universal lingua franca among diverse, distributed systems is going to become more and more evident to software engineers and business leaders alike. Just ask the teams responsible for 2013’s internationally mocked failure, Healthcare.gov, whose extent of brokenness lay in direct proportion to the sheer number of independent, distinctive APIs it was trying to connect, spanning state healthcare website logins to insurance-providers’ customer databases. Hypermedia, while not without its own problems and limitations, has the potential to succeed in overcoming such communication gaps, especially where Big Data is concerned. And the World Wide Web, again, is the ideal case in point. There is no bigger data array known to humankind, and yet any of that data can be accessed anytime, from anywhere in the world, on any device, with just the click of a link. Hypermedia is powerful, and its ultimate potential is anything but clear. It may even one day leave today’s REST and HTTP methods behind, as some developers are already anticipating, relying on its basic strength—namely, its ability to link, through a common protocol, nonlinearly distributed data—in order to carry it forward into new digital horizons. But considering that hypermedia’s API tide is only just beginning to rise, you still have an opportunity to consciously decide to sink or swim.
Written by: Tom Huston
Further Resources