Designing, implementing, and maintaining APIs for the Web is more than a challenge; for many companies, it is an imperative. This series takes the reader on a journey from determining the business case for APIs to a design methodology, meeting implementation challenges, and taking the long view on maintaining public APIs on the Web over time. Along the way there are interviews with influential individuals and even a suggested reading list on APIs and related topics.
This InfoQ article is part of the series “Web APIs From Start to Finish”. You can subscribe to receive notifications via RSS.
I am regularly asked which books I recommend for those who want to learn more about designing, impelementing, and maintaining APIs for the Web. Here’s a short list that covers quite a bit of ground with a mimimum amount of reading. These are books I found as I was learning about APIs and many of them are still on my "go-to" shelf -- the shelf that holds the books I consult most often.
I’ve included two book lists (Primary and Secondary). In the first list are books that speak directly to the work of HTTP, APIs, REST, and Hypermedia. These are certainly not the only books on these subjects but they are the ones I find myself referring to most often in my own work.
The second list contains books that, while not directly in the field of APIs, have affected my thinking on the way we design and implement stuff on the Web. I had a hard time narrowing down this list and there are quite a few more I’d add but I’ll save that for another time.
Finally, I added a section named "Other Resources." These are sources that I have found useful over time that are not in full-on book form. Mostly these are blog posts, peer-reviewed papers, etc. that cover topics that come up when working through a tough problem or trying to get a handle on the concepts behind common practice and theory. I often keep bookmarks to these items close at hand.
Primary Books
RESTful Web Services(2008), Richardson and Ruby
This is an essential book. It was one of the first books to document the Create-Read-Update-Delete (CRUD) style of HTTP APIs -- a style that is still the most commonly-used way to create "RESTful" APIs today. The writing style is excellent and the material top-notch. It’s also cool that Leonard Richardson and the publisher O’Reilly Media have released this under the Creative Commons License in several eBook formats. You should definitely have this one handy.
HTTP Developer’s Handbook(2003), Chris Shiflet
I found this book to be an excellent guide and reference for the HTTP protocol and for writing programs that utilize HTTP. I still refer to this book when trying to grok HTTP edge cases. Well-written and organized, I still love this book.
RESTful Web Services Cookbook(2010), Subbu Allamarju
This is a great set of clear recipes for solving real-world problems for HTTP APIs. While it covers the usual things like designing URIs, payloads, and handling status codes, etc. what I really like about this book are the recipes for supporting async operations, long query strings, and what Allamaraju calls "HTTP Controllers." I’m on my second copy and it’s already well worn.
REST in Practice(2010), Webber, Parastatidis, & Robinson
This book has as distinct enterprise feel and was one of the first to illustrate the use of hypermedia for business applications. The "RESTBucks" Coffee shop sample app is an oft-cited example. With example code in both C# and Java, this book speaks to common enterprise developers as well as those interested in what it is like to mount a full-featured app from start to finish.
Building Hypermedia APIs with HTML5 and Node(2011), Amundsen
I wrote this book to explore the parts of the REST architecture that Fielding had left out -- the details behind the "hypermedia as the engine of application state" (HATEOAS) parts. It’s a very short book covering example hypermedia designs in XML, JSON, and HTML. I’ve had lots of positive comments on the book and often find references and examples from the book showing up online and in customers' internal materials.
REST API Design Rule Book(2011), Mark Masse
This book is a good source of design patterns for CRUD-style APIs. It covers the basics like URI design for singluars, plurals, and operations as well as a decent review of the HTTP spec for methods, headers, and status codes. For me, there is a bit too much reliance on Masse’s own WRML format but that is just my personal preference.
RESTful Web APIs(2013), Richardson and Amundsen
This book (RWA) is the "follow-on" to Richardson and Ruby’s RESTful Web Services (RWS) and covers a lot of new territory. Where RWS focused on HTTP resources, RWA emphasizes hypermedia formats. It dips a toe into the Semantic Web waters with reviews of a handful of RDF-based formats and the introduction fo "Profiles" to help carry application-level meaning into the Web API space. It was fun for me to work with Leonard Richardson on this and we have gotten lots of great feedback on the book.
Secondary Books
I read quite a few books and find some that are technically "out of the field" of APIs, HTTP, and REST are still quite helpful to me when I am working on designing and implementing distributed apps. Here are a few of my top picks for expanding your mind outside the typical API readings.
The Design of Everyday Things(1988-2002) Donald Norman
Originally published in 1988, this book sets the groundwork for the field of Human-Computer Iteraction (HCI) and what we know as Usability. Norman works through all sorts of examples of how humans and devices interact (not just computers) and defines his Action Lifecycle, clarifies the notion of "Affordance" and gives some excellent advice on how to think about designing user interfaces based on your audience, the environment in which the device is used, and the goal you have in mind as a designer. This is a must-have for your bookshelf.
In Search of Certainty(2013) by Mark Burgess
Burgess is the creator of the CFEngine technology that acts as an independent agent that monitors large-scale infrastructure. His experience in this work led him to apply an immunology model to complex computer systems and the book chronicles his journey from a basic idea to a full-on set of tools that have thier own "agency" on the network. I like the writing style and all the great references to physics, brain science, and the history of computing in general. Toward the end there is a bit more reference to his product than I’d prefer but it makes sense since it is the work on CFEngine that brings all these themes together. A great book to get you thinking about what it takes to create safe and successful autonomous bots on the network.
Information: A History, a Theory, a Flood(2012), James Gleick
Gleick’s 1987 book Chaos popularized the concepts in Chaos Theory and this book does the same for Information Theory. He has a great storytelling style and covers quite a bit of ground in this 300+ page book. From remote drumming to quantum computing, Gleick covers it all with excellent stories and real insight. I still go back and read sections of this book just for the enjoyment.
Information : A Very Short Introduction(2010),Luciano Floridi
This is a very handy text to get the basics in Information Theory. It starts with a clear explanation on how data is different than information and talks about how information theory is tied up with math, physics, biology, economics, and even social ethics. Where Gleick tells storys, Floridi lays out the facts and links between fields of study. These two books make a great pair.
Memory Machines: The Evolution of Hypertext(2013), Belinda Barnet
If you want to know the backstage story of how hypertext was concieved, morphed, and grew over the last 50 years (yes one half century) then this is book for you. Barnet has collected personal interviews with Ted Nelson, Douglas Englebart, Tim Berners-Lee and many others. Along the way you get a picture of how competing ideas and market forces shaped the hypertext/hypermedia world we experience today. And you learn about many initial ideas on the use and implementation of hypertext that are still not available.
Complexity: A Guided Tour(2011), Melanie Mitchell
This is a very accessible book on the world of Complexity Theory. Mitchell takes the reader through a bit of history, genetic programming theory for devices and automata programming for large systems. Along the way there are lots of clear examples and even references to running code. An excellent text for anyone interested in digging into this huge topic.
Other Sources
Here are papers, blog posts and other sources I keep handy for review and reference. These are the links I often send to others when they ask for examples, clarification, or background on a topic.
Architectural Styles and the Design of Network-based Software Architectures(2000), Roy T. Fielding
This is the dissertation and launched a thousand arguments(grin). Seriously, this is a document everyone in the API-space should read. It’s not long and it’s relatively easy to read. And it is the document that defines the term REST. Often, if people read this one at all, they only read Chapter 5 : "Representational State Transfer (REST)." To me that is not the best part of the dissertation. Instead, I like Chapter 2 : "Network-based Application Architectures" where the rationale and desired outcome for building distributed systems is described. In fact, here’s my recommendation on how to read this disseration. Do it in the following order: Chapters 2, 1, 4, 3, 6, and 5. That’s right -- read the REST chapter last. I think it makes a lot more sense when you do this.
REST APIs must be hypertext-driven(2008), Roy T. Fielding
The same year RESTful Web Services was released Fielding published this now (in)famous blog post explaining that hypermedia (he uses the word hypertext) is required element for his REST style. And in another important step, he uses this blog post to expand on what he meant by the phrase "hypertext as the engine of application state"—what people have gotten into the habit of calling HATEOAS and what Fielding prefers to call the "Hypermedia Constraint." Hint: The comment thread on this blog post is one of the most valuable conversations I’ve seen Fielding engage in on the topic of REST.
What’s different/better/worse than other JSON hypermedia media types?(2013) Swiber, et al
In mid-2013, someone opened in issue in Kevin Swiber’s Siren JSON hypermedia format repo asking a great question about how to make choices in which hypermedia JSON format to use for implementation. And the comment thread on this issue is pure gold. Most of the authors of these popular formats (Mike Kelly for HAL, Kevin Swiber for Siren, Jorn Wildt for MASON, myself for Collection+JSON) chime in and there are quite a number of insights in this thread. If you’re contemplating selecting a JSON format for hypermedia, this is a great resource for commentary.
Hypermedia Types(2011), Amundsen
This is a series of Web pages I started in 2010 in order to analyse and categorize hypermedia formats based on a set of properties that all hypermedia types will exhibit. A set of elements called "H-Factors" are defined to help study how hypermedia actually works for inline business applications and this has been picked up by several other people to help in both design and analysis of hypermedia formats. It’s a work in progress and I sometimes pass this link to folks asking about some fundamentals of what hypermedia controls are and how they work.
How to Follow Instructions(2012), Richardson
This is a great presentation by Leonard Richardson on how hypermedia can help create machine readable instructions for clients to follow. He adopts a great point of view (recalling the days of Bulletin Board Systems (BBSs) and file servers before HTTP and links were common) and the slides are excellent, too. Well worth the 50 minutes it takes to view the entire presentation.
Designing Hypermedia APIs(2012-2014), Klabnik
Steve Klabnik is a great resource for down-to-earth, no-nonsense advice on what it takes to actually implement running code that uses hypermedia. He started this kind of "living book" covering hypermedia back in 2012 and continues to add to it now and again. If you’re looking for a complete story, cover-to-cover, this is probably not a good resource for you. However, if you want to keep a eye on the ever-growing body of knowledge on what it is like to actually build and maintain these types of systems, Klabnik’s Designing Hypermedia APIs is a great addition to your regular reading. I keep this material handy and always look forward to his periodic updates.
Conclusion
Well, that’s a tour through my top-level bookshelf and my common bookmarks. There are quite a number of other books and links worth sharing but this, IMO, is a good start. If you have other sources you use often when you are designing and implementation Web APIs, I’d love to hear about them. Add them to the comment thread on this story and let’s see what develops.
About the Author
Mike Amundsen is the Director of Architecture for the API Academy at CA / Layer 7. He is responsible for helping companies to capitalize on the myriad opportunities APIs present to both consumers and the enterprise. He's an internationally recognized industry expert on distributed network architecture, Web development, cloud computing and more. He has authored numerous books and papers over the last 15 years. His latest book (with Leonard Richardson) is "RESTful Web APIs". His book “Building Hypermedia APIs with HTML5 and Node" (2011) is an oft-cited reference on building hypermedia-based business applications.
Designing, implementing, and maintaining APIs for the Web is more than a challenge; for many companies, it is an imperative. This series takes the reader on a journey from determining the business case for APIs to a design methodology, meeting implementation challenges, and taking the long view on maintaining public APIs on the Web over time. Along the way there are interviews with influential individuals and even a suggested reading list on APIs and related topics.
This InfoQ article is part of the series “Web APIs From Start to Finish”. You can subscribe to receive notifications via RSS.