Designing Hypermedia APIs

The Beginning of the End

September 30, 2013

Today sees a big update, you all should be getting emails shortly. There's two major changes:

Higher quality output

I've converted the entire thing over to my own little homegrown book building framework, words. Basically, I use make and pandoc and that's it. This builds faster, makes smaller books, and makes actually valid epubs. Thanks Calibre! Anyway, you should see nicer output. Let me know what you think, I bet this can be improved even more in the future.

Reorganization and final TOC

Basically, everything I've done so far is the second half of the book, which I'm calling the 'notebook'. This is just a loose collection of essays, as you know. The first half will be more like a traditional book. I've sketched out the TOC, and here it is:

Main content

  • Introduction
  • The game plan
  • REST vs. Hypermedia
  • Affordances, or “I don’t know what I’m doing”
  • Caching
  • Educating Others
  • Hyperpizza
  • Media Types
  • Polling is awesome
  • Reusable tools
  • Should I build a hypermedia API?
  • Users and auth
  • Versioning


  • Hypermedia API 11
  • REST
  • Web Worship
  • Hypermedia Benefits in Plain Language
  • Linking
  • Hypertext
  • Programming the media type
  • The Design Process: An Overview
  • Media Type
  • Building the W3CLove API
  • APIs Should Expose Workflows
  • Transmuting Philosophy into Machinery
  • Distributed Application Architecture
  • Application Architecture
  • Software Architectural Style
  • Human vs Machine Interaction
  • Introduction to Hypermedia Clients
  • Versioning is an anti-pattern
  • Out of Band
  • Partial application of Hypermedia
  • Get A Job! - An Introduction
  • Get a Job: The Basics
  • The Hypermedia Proxy pattern
  • Much ado about PATCH

Right now, the book is about 80 pages in length. I expect that to a little more than double, we'll see.

Other, future changes

Soon, I hope to introduce HTML as an additional format, like I promised many of you ago. I'm also hoping to get on a regular schedule again...