RESTful Web APIs

Chapter 7. Pure-Hypermedia Designs

The collection pattern is powerful, but it’s not ubiquitous. The maze game from Chapter 5 could technically be implemented with Collection+JSON representations, but it would look terrible. The whole point of the game is that the client sees one cell at a time. There’s nothing to “collect” inside a collection. The application semantics of the maze game don’t match what the collection pattern can provide.

Nothing says you have to use the collection pattern, but it is the most popular design pattern for APIs. If you want to implement some other pattern, or if your API design doesn’t fit any particular pattern, you can describe an API’s semantics using pure hypermedia. You don’t have to create an entirely new standard like Maze+XML, with its own media type. You can represent the state of your resources using a generic hypermedia language.

In this chapter, I’ll discuss APIs that use a generic hypermedia language as their representation format. I’ll talk about a number of newfangled representation formats, but the focus of my explanation will be an old format that you’re already familiar with: HTML.

Why HTML?

We think of HTML in the context of the World Wide Web: a network of documents intended to be read by human beings. That popularity makes it the obvious choice for any part of an API that serves documents intended for human consumption. Even if the rest of your API serves XML- or JSON-based representations, you can use HTML for the parts that will be ...