I’ve shown representations for the planet list, for maps of the planets, and for points on the maps. But how are you supposed to get from the planet list to, say, the road map of Earth? Presumably you click “Earth” in the planet list, sending a GET request to /Earth, and get back a representation of Earth. This representation includes a bunch of links to maps of Earth. At this point you follow a second link to the road map of Earth. Well, I just described the representation of Earth. My representation of a planet contains whatever useful information I have about the planet, as well as a set of links to other resources: maps of the planet (see Example 5-7).
Example 5-7. An XHTML representation of a place: the planet Earth <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head><title>Earth</title></head> <body> <dl class="place"> <dt>name</dt> <dd>Earth</dd> <dt>maps</dt> <dd> <ul class="maps">
<li><a class="map" href="/road/Earth">Road</a></li> <li><a class="map" href="/satellite/Earth">Satellite</a> ... </ul> </dd> <dt>type</dt> <dd>planet</dd> <dt>description</dt> <dd>
Third planet from Sol. Inhabited by bipeds so amazingly primitive that they still think digital watches are a pretty neat idea. </dd>
</dl> </body> </html>
I’ve chosen to represent places as lists of key-value pairs. Here, the “place” is the planet Earth itself. Earth in this system is a named place, just like San Francisco or Egypt. I’m representing it using the dd tag: HTML’s standard way of presenting a set of key-value pairs. Like any place, Earth has a name, a type, a description, and a list of maps: links to all the resources that map this place.
Why am I representing a planet as a place? Because now my clients can parse the rep- resentation of a planet with the same code they use to parse the representation of a place. Example 5-8 is a representation for Mount Rushmore on Earth. You might get this XHTML file back in response to a GET request for /Earth/USA/Mount%20Rushmore. Example 5-8. An XHTML representation of a place: Mount Rushmore
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head><title>Mount Rushmore</title></head> <body> <ul class="places"> <li> <dl class="place">
<dt>name</dt> <dd>Mount Rushmore</dd> <dt>location</dt>
<dd>
<a class="coordinates" href="/Earth/43.9;-95.9">43.9°N 95.8°W</a> </dd>
<dt>maps</dt> <ul class="maps">
<li><a class="map" href="/road/Earth/43.9;-95.9">Road</a></dd> <li><a class="map" href="/satellite/Earth/43.9;-95.9">Satellite</a> ... </ul> </dd> <dt>type</dt> <dd>monument</dd> <dt>description</dt> <dd>
Officially dedicated in 1991. Under the jurisdiction of the <a href="http://www.nps.gov/">National Park Service</a>. </dd>
</dl> </li> </body> </html>
Rather than serve a map image of Mount Rushmore, or even an XHTML page that links to that image, this representation links to resources I’ve already defined: maps of the geographical point where Mount Rushmore happens to be located. Those resources take care of all the imagery and navigation details. The purpose of this resource is to talk about the state of the place, and what it looks like on a map is just one bit of that
state. There’s also its name, its type (“monument”), and its description. The only dif- ference between the representation of a planet and that of a place is that a place has a location in its definition list, and a planet doesn’t. A client can parse both representa- tions with the same code.
You may also have noticed that you don’t have to write a special client for this web service at all. You can use a plain old web browser. Starting at the home page (http:// maps.example.com/), you click a link (“Earth”) to select a planet. You get the repre- sentation shown in Example 5-7, and you click “Road” to see a road map of Earth. Then you navigate that map by clicking links (“North,” “Zoom out”). My web service is also a web site! It’s not a very pretty web site, because it’s designed to be used by a computer program, but nothing prevents a human from consuming it (or debugging it) with a web browser.
If you get only one thing out of this book, I hope it’s that this idea starts seeming natural to you (assuming it didn’t before). Web services are just web sites for robots. My map service is particularly web site-like: it connects its resources together with hypermedia, the hypermedia representations happen to be HTML documents, and (so far) it doesn’t use any features that web browsers don’t support. But all RESTful resource-oriented web services partake of the nature of the Web, even if you can’t use them with a standard web browser.
Example 5-9 shows one more representation: the representation of a point on the map. Example 5-9. An XHTML representation of the point 43.9°N 103.46°W on Earth
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head>
<title>43.9°N 103.46°W on Earth</title> </head>
<body> <p> Welcome to
<a class="coordinates" href="/Earth/43.9;-103.46">43.9°N 103.46°W</a>
on scenic <a class="place" href="/Earth">Earth</a>. </p>
<p>See this location on a map:</p> <ul class="maps">
<li><a class="map" href="/road/Earth/43.9;-95.9">Road</a></li>
<li><a class="map" href="/satellite/Earth/43.9;-95.9">Satellite</a></li> ...
</ul>
<ul class="places">
<li><a href="/Earth/43.9;-95.9/Mount%20Rushmore">Mount Rushmore</a></li> </ul>
<form id="searchPlace" method="get" action=""> <p>
Show nearby places, features, or businesses:
<input name="show" repeat="template" /> <input class="submit" /> </p>
</form> </body> </html>
This representation consists entirely of links: links to maps centered around this point, and links to places located at this point. It has no state of its own. It’s just a gateway to other, more interesting resources.