Over the past three chapters, I’ve built up a set of rules for
designing a brand new API. There’s still some work to do on these
rules, but I can now present them in something approaching their
Is there a domain-specific standard for your problem? If so, use
it. Document any application-specific extensions (Chapter 5).
Does your problem fit the collection pattern? If so, adopt one of
the collection standards. Define an application-specific vocabulary
and document it (Chapter 6).
If neither of those is true, choose a general hypermedia format. Break
down your application into its state transitions. Document those state
transitions (Chapter 7).
At this point, you have your protocol semantics nailed down. The
application semantics are all that remain. Are there existing
microdata items or microformats that cover your problem domain? If
so, use them. Otherwise, define an application-specific vocabulary and
document it (Chapter 7).
The issue here is not whether to use “hypermedia.” Maze+XML, AtomPub,
and HAL all use hypermedia to describe state transitions, but they use
it in different ways to solve different problems. The issue is
choosing a format that lets you represent the state transitions that
make up your API.
HAL is great for read-only applications. Maze+XML is great for read-only applications that happen to be maze games. AtomPub is great for read-write applications that work more or less like weblogs. Move outside a format’s comfort zone, ...