Building Hypermedia APIs with HTML5 and Node

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 book’s 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 don’t 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 author’s 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.

What Is Not Covered

While the examples in this book use HTML5, Node.js, and CouchDB, this book should not be used as a source for learning these technologies. Astute readers may find the author’s use of these tools—HTML5, Node.js, CouchDB—somewhat stilted and possibly, to some, blasphemous. The author makes no claims at expertise in these technologies. Instead, in the context of this book, they are used as tools for illustrating points about hypermedia design and implementation. The appendices list several good books on the technologies used in the writing of this text that the reader is encouraged to refer to for a more authoritative voice on these matters.

This book does not cover the details of the HTTP protocol and associated web standards. There is a wealth of writing available and the appendices reference important RFCs and other standards documents used while preparing this text. The reader will also find several book recommendations in the appendices well worth the time to read and become acquainted.

Finally, while the subject of the Representation State Transfer (REST) architectural style comes up occasionally, this book does not explore the topic at all. 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. Readers who want to learn more about Fielding’s style will find helpful recommendations in the appendices.

Contents of This Book

The book is designed to allow readers to jump around to sections they find interesting; you do not need to read it cover-to-cover in sequential order. There are a number of links within the chapters to point the reader to related material that may have been missed when skipping around in the text. Hopefully this format will also make the text more useful as a reference when the reader wants to refer back to content at a later date.

The general layout of the book is as follows:

Chapter 1: Understanding Hypermedia

This is the conceptual chapter of the book. It provides some historical references for hypermedia, HTTP, and HTML, and then goes on to lay out the basic premise of the text including making a case for more hypermedia, offering an analysis of existing hypermedia content, and a suggested methodology for creating new hypermedia designs.

Chapters 2, 3, and 4: Implementations

The middle chapters contain complete walk-throughs of fully functional hypermedia examples. These chapters are meant to lead the reader through the process of assessing an application scenario, selecting design elements, creating sample data, and implementing complete server and client solutions that meet the use case requirements. While the examples are kept relatively basic, they are still meant to convey most of the details the reader is expected to encounter when creating real-life production-ready solutions.

Chapter 5: Documenting Hypermedia

This is the housekeeping chapter of the book. It provides tips on documenting media type designs and registering those designs with standards bodies such as the IANA, IEFT, and WC3. There is a section covering the concepts of Versioning and Extending hypermedia types as well as some general tips on good API and hypermedia designs.

Appendices

This book contains a number of appendices. These are included as pointers to quoted and referenced materials as well as to hold additional content that did not fit well into the flow of the chapters. The information here may also be valuable for future reference after the reader has already completed the body of the book.

Coding Style for This Book

One of the reasons Node.js and CouchDB were selected for this book is that, from the beginning, these products are HTTP-aware. That means the software works well using the existing HTTP application protocol and in a state-less environment like the World Wide Web. As a result, there is very little friction between the components I created using Node and CouchDB, and the protocol used to communicate with those components.

It is also an advantage that these software systems all use the same front-facing programming language for scripting (Javascript). While not all readers will be proficient in Javascript, hopefully this single language format can reduce the need for mental context-switching when moving between client code, server code, and data storage implementation.

The important point, though, is that the software is not the focus for this book; it is merely the medium for the hypermedia message. You will likely find that many of the examples contain code that is either too brief or too fragile to run in a production environment. This is mostly a matter of expediency; I’m anxious to illustrate the details of the hypermedia, not the code used to implement that design. These designs will work well when implemented for any platform, using any language, running on any operating system. I suspect many readers will find better ways to implement these media type designs using their own languages and platforms, and that’s all the better.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This icon signifies a tip, suggestion, or general note.

Caution

This icon indicates a warning or caution.

Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Building Hypermedia APIs with HTML5 and Node by Mike Amundsen (O’Reilly). Copyright 2012 O’Reilly Media, Inc., 978-1-449-30657-1.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that lets you easily search over 7,500 technology and creative reference books and videos to find the answers you need quickly.

With a subscription, you can read any page and watch any video from our library online. Read books on your cell phone and mobile devices. Access new titles before they are available for print, and get exclusive access to manuscripts in development and post feedback for the authors. Copy and paste code samples, organize your favorites, download chapters, bookmark key sections, create notes, print out pages, and benefit from tons of other time-saving features.

O’Reilly Media has uploaded this book to the Safari Books Online service. To have full digital access to this book and others on similar topics from O’Reilly and other publishers, sign up for free at http://my.safaribooksonline.com.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:

http://shop.oreilly.com/product/0636920020530.do

To comment or ask technical questions about this book, send email to:

[e-mail]

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgements

There are quite a number of people who deserve acknowledgement for the completion of this book.

Several people volunteered to review early drafts of this book and provided excellent feedback and suggestions. Thanks to Leonard Richardson, Erik Wilde, Ian Robinson, Jan Algermissen, Mike Kelly, Will Hartung, William Martinez Pomares, Erlend Hamnaberg, Darrel Miller, Glenn Block, David Zulke, Erik Morgensen, Kevin Burns Jr., Jonathan Moore, and Subbu Allamaraju. If the book is accurate, clear, and concise, that is likely due to the contributions of these individuals. Any remaining shortcomings are solely the responsibility of the author.

Julian Reschke, Mykyta Yevstifeyev, Frank Ellermann, and others were very helpful and generous as I worked to learn the details of IETF and IANA procedures and processes.

I’d like to thank Benjamin Young for introducing me to CouchDB and for all his efforts to teach me how to improve my understanding and coding of CouchDB. His willingness to spend one-on-one time to help me get past some hurdles was invaluable. If there are shortcomings or errors in the CouchDB code, it’s most likely because I failed to grasp what Benjamin tried to teach me; my apologies to the reader and to Benjamin Young.

Simon St. Laurent, my editor, has been a great champion of this book. Without his tireless efforts, this book would never have seen the light of day. Thanks also to Melanie Yarbrough for all her proofreading and editing work.

I want to thank the organizers of CodeStock, Stir Trek, JAOO (aka Gotocon), and OSCON. My presentations at these and other events over the last few years has given me a chance to explore, refine, and correct initial concepts and methodologies.

I owe special thanks to all of the attendees of REST Fest 2010 and 2011. It was during very productive and enjoyable weekends in lovely Greenville, South Carolina, that I was able to first publicly describe and refine my ideas about analyzing and designing hypermedia.

I’ve benefited quite a bit from the conversations on the REST IRC channel on freenode.org. My thanks to all who hang out there for all of the great feedback and ideas.

Thanks, finally, to the moderators and members of the REST-Discuss list. Over the years I’ve posted many questions, assertions, and comments to that list in an effort to learn more about Fielding’s style and HTTP implementation in general. In most cases, many of the correct things I learned about REST and HTTP were a result of my REST-Discuss experience.