Download
Introduction
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.
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 reallife 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
