Cover by Sam Ruby, Leonard Richardson

Safari, the world’s most comprehensive technology and business learning platform.

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required

O'Reilly logo

Link the Resources to Each Other

Since I designed all my resources in parallel, they’re already full of links to each other (see Figure 5-3). A client can get the service’s “home page” (the planet list), follow a link to a specific planet, follow another link to a specific map, and then follow navigation and zoom links to jump around the map. A client can do a search for places that meet certain criteria, click one of the search results to find out more about the place, then follow another link to locate the place on a map.

One thing is still missing, though. How is the client supposed to get to a list of search results? I’ve set up rules for what the URI to a set of search results looks like, but if clients have to follow rules to generate URIs, my service isn’t well connected.

I want to make it possible for a client to get from /Earth/USA/Mount%20Rushmore to /Earth/USA/Mount%20Rushmore?show=diners. But it does no good to link to “diners” specifically: that’s just one of infinitely many things a client might search for. I can’t put infinitely many links in the representation of /Earth/USA/Mount%20Rushmore just in case someone decides to search for pet stores or meteor craters near Mount Rushmore.

HTML solves this problem with forms. By sending an appropriate form in a representation, I can tell the client how to plug variables into a query string. The form represents infinitely many URIs, all of which follow a certain pattern. I’m going to extend my representations of places (like the one in Example 5-8) by including this HTML form (see Example 5-11).

Example 5-11. An HTML form for searching a place

<form id="searchPlace" method="get" action="">
 <p>
  Show places, features, or businesses: 
  <input id="term" repeat="template" name="show" /> 
  <input class="submit" />
 </p>
</form></screen>

A person using a web browser would see this form as a set of GUI elements: a text box, a button, and a set of labels. They’d put some data into the text box, click the button, and be taken to another URI. If they were at /Earth/USA/Mount%20Rushmore, and they’d typed in “diners,” their web browser would make a GET request to /Earth/USA/Mount%20Rushmore?show=diners. An automatic client can’t display the form to a human, but it would work the same way. Given a preprogrammed desire to search a place, it would look for the searchPlace form and use the form definition as a guide to constructing the URI /Earth/USA/Mount%20Rushmore?show=diners.

Note

You probably haven’t seen the repeat="template" syntax before. It’s a feature of XHTML 5, which is still being designed as this book goes to press. Occasionally in this chapter and the next, I’ll introduce a feature of XHTML 5 to work around the shortcomings of XHTML 4 as a hypermedia format.

The problem here is that my service accepts any number of values for the query variable show. A client can make a simple search such as ?show=diners or perform a complicated search such as ?show=diners&show=arsenic&show=towns&show=oil+tankers.

A form in XHTML 4 could allow the latter request if it showed four text boxes, all called show. But an HTML form can never show an arbitrary number of text boxes, which is what I need to truly capture the capabilities of my service. XHTML 5 has a feature called the repetition model, which allows me to express an arbitrary number of text boxes without writing an infinitely long HTML page.

The path from the service root to a diner near Mount Rushmore

Figure 5-4. The path from the service root to a diner near Mount Rushmore

Now my service is better connected. It’s now possible to get from the list of planets to a description of a diner near Mount Rushmore (assuming there is one). Figure 5-4 illustrates the journey. Starting at the service root (/), the client selects the planet Earth (/Earth). The client uses the HTML form in that representation to search for places called “Mount Rushmore” on Earth (/Earth?show=Mount%20Rushmore). Hopefully the top search result will be Mount Rushmore itself, and the client can follow the first search result link to /Earth/USA/Mount%20Rushmore. The representation of Mount Rushmore has a search form too, and the client enters “diners” in that. Assuming there are any nearby diners, the client can follow the first search result link to find a diner near Mount Rushmore.

The search function doesn’t just keep clients from having to mint their own URIs. It resolves human place names, which are always fuzzy, into canonical resource URIs. A client should be also be able to search for “Mount Rushmore National Monument” and get /Earth/USA/Mount%20Rushmore as a search result, just like the client can search for “Springfield” and pick which Springfield they mean. This is a useful feature for any client that lets users type in their own place names.

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required