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.

The maze (top view)
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 ...

Get RESTful Web APIs now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.