Foreword
Leonard Richardson, November 2011
You cant talk about something if you dont have the words.
The World Wide Web is driven by hypermedia: the ability of a document to describe its possible states, and its relationship to other documents. Hypermedia is not just a way of making websites that average people can use; its a new style for distributed computing, powerful and flexible.
Theres nothing new about the web technologies or the hypermedia concept: in another world, we could have been using hypermedia for distributed computing since the mid-1990s. Instead, weve been slow to adopt hypermedia for anything but consumer use. Its an easy concept to grasp intuitivelywe all use the Webbut its difficult to understand in a context of development.
Our problems stem from conceptual blocks. The Web invaded our everyday lives years before its architecture was formally described. Weve spent the twenty-first century making gradual progress, coming up with new vocabulary to help developers come to terms with the power of the Webpower that was there all along.
The description of hypermedia youll read in this book is, in my opinion, one of the biggest conceptual advances since Roy Fielding first defined the REST architectural style. Mike Amundsen has taken the blanket term hypermedia and taken it apart to see exactly what it can mean and how it works.
What makes a data format useful for some applications and not others? Why is HTML so versatile, even for nonconsumer applications, and where does it fall short? Under Mikes view of hypermedia, these questions have precise answersanswers that I hope will drive the next generation of web services and web-based technologies.
Mike has not only found the words to describe hypermedia, hes given voice to our intuitions about how it works.
Preface
When you set out on your journey to Ithaca, pray that the road is long, full of adventure, full of knowledge.
- Constantine P. Cavafy
Hypermedia API Design
This books primary focus is on designing hypermedia APIs. That may seem a bit strange to some readers. There are many books on programming languages, data storage systems, web frameworks, etc. This is not one of those books. Instead, this book covers the nature of the messages passed between client and server, and how to improve the content and value of those messages. I, personally, find this to be an exciting and fascinating area.
As of this writing anecdotal trends seem to indicate an ever-increasing reliance on APIs in web development. In general, this is a good thing. It means more and more developers are catching on to the notion that the World Wide Web is a great place to share not only data, but also services, a goal of those who championed the web in its early days.
However, I believe that this explosion of web APIs may lead us down a troublesome path. In my experience over the last few years, I have seen too many examples of implementations that rely on concepts of APIs rooted in desktop and local area network patterns that will not scale well at the WWW level, solutions still exhibiting brittleness that can lead to costly and frustrating maintenance issues as time goes by. In short, I dont see enough hypermedia in API offerings for the web.
This book is an attempt to improve the chances that new APIs added to the WWW will be easier to use and maintain over time, and that they will take their cue from those who were responsible for the discovery of the value of hypermedia linking; the codification of the HTTP protocol; and the implementation of HTML, Atom/AtomPub, and other native hypermedia formats that still drive the growth of the web today.
Intended Audience
The primary goal of this book is to increase both the quantity and quality of hypermedia content in use on the web. To that end, the audience for this text is two-fold.
First, this book is offered as a guide to system architects. Hopefully the text can be a valuable guide for those responsible for designing systems that rely on hypermedia to improve the evolvability and stability of long-lived implementations. When viewed as an integral part of system architecture, hypermedia provides a wealth of possibilities to architects. Hopefully this book will illustrate that, by treating hypermedia data as a key architectural component (rather than merely a payload to be pushed about by clients and servers), architects can increase future stability and flexibility of their systems.
Second, readers tasked with implementing clients and servers will find valuable advice and examples on how to deal with hypermedia messages themselves. Up to now, most books on web implementations have focused too often on the role of servers in dealing hypermedia. It is the authors view that this oversight too often results in improper client implementations that not only ignore, but often negate the value of hypermedia messages on the web. One of the key advantages of hypermedia as an architectural pillar is that hypermedia encourages clients to code for the media type instead of writing applications that treat messages as simple data. Writing hypermedia-aware clients is a skill that takes time to master. And while this book does not focus solely on writing hypermedia clients, the author hopes that it will show enough examples and advantages as to spur other, more talented individuals to establish new practices and techniques aimed at taking direct advantage of hypermedia.