Mike Amundsen - Building Hypermedia APIs with HTML5 and Node

Copyright 2011 Amundsen.com, Inc.

OReilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (.

Nutshell Handbook, the Nutshell Handbook logo, and the OReilly logo are registered trademarks of OReilly Media, Inc. Building Hypermedia APIs with HTML5 and Node , the image of a rough-legged buzzard, and related trade dress are trademarks of OReilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and OReilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

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.

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.