RESTful Web APIs

Chapter 5. Domain-Specific Designs

In this chapter, I’ll choose a problem space and implement a web API for representing it. The details of the problem space don’t matter. The technique is always the same. So I’m going to choose the most frivolous example I can think of: maze games!

Figure 5-1 shows a simple maze with one entrance and one exit. My server’s job will be to invent mazes like this and present them to clients.

Figure 5-1. The example maze (a view from above)

Although this is a frivolous example, the maze is a good metaphor for hypermedia applications in general. Any complex problem can be represented as a hypermedia maze that the client must navigate. If you’ve ever been trapped in a phone tree, or searched for products on an online store and then bought something from the search results, you’ve navigated a hypermedia maze.

I’ve seen hypermedia APIs for modifying complex insurance policies; for selecting products from a catalog and paying for them; and, yes, for describing phone trees (see VoiceXML in Chapter 10). All of these APIs have the same shape as the maze games I’m about to show you:

• The problem is too complex to be understood all at once, so it’s split up into steps.
• Every client begins the process at the same first step.
• At each step in the process, the server presents the client with a number of possible next steps.
• At each step, the client ...