I’ve come up with a procedure to follow once you have an idea of what you want your program to do.†It produces a set of resources that respond to a read-only subset of HTTP’s uniform interface: GET and possibly HEAD. Once you get to the end of this procedure, you should be ready to implement your resources in whatever language and framework you like. If you want to expose a larger subset of the uniform interface, I present a slightly extended procedure in Chapter 6.
1. Figure out the data set
2. Split the data set into resources For each kind of resource: 3. Name the resources with URIs
4. Expose a subset of the uniform interface
†This procedure has a lot in common with Joe Gregorio’s “How to create a REST Protocol” (http://
www.xml.com/pub/a/2004/12/01/restful-web.html).
5. Design the representation(s) accepted from the client 6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia links and forms 8. Consider the typical course of events: what’s supposed to happen?
9. Consider error conditions: what might go wrong?
In the sections to come, I’ll show, step by step, how following this procedure results in a RESTful web service that works like the Web. The only difference between what I do and what this procedure says is that I’m going to design all my resources at once, rather than take you through the same steps over and over again for each kind of resource.
Figure Out the Data Set
A web service starts with a data set, or at least an idea for one. This is the data set you’ll be exposing and/or getting your users to build. Earlier I said my data set would be maps, but which maps? This is a fantasy, so I’ll spread the net wide. My imaginary web service will serve maps in all projections and at all scales. Maps of the past, the present, and the supposed future. Maps of other planets and of individual cities. Political maps, road maps (which are just very detailed political maps), physical maps, geological maps, and topographic maps.
This is not every kind of map. I’ll only serve maps that use a standard 2-D coordinate system: a way of identifying any given point on the map. The map need not be accurate, but it must be addressable (there’s that word again) using latitude and longitude. This means I won’t serve most maps of fictional places, maps that arbitrarily distort geog- raphy (the way subway maps do), or maps created before longitude could be measured accurately.
Maps are made out of points: in this case, points of latitude and longitude. Every map contains an infinite number of points, but I can have a map without keeping every one of those points in my data set. I just need some image data and a couple basic pieces of information about the map: what are the latitude and longitude of the map’s corners? Or, if the map covers an entire planet, where on the map is the prime meridian?‡Given that information, I can use standard geographical algorithms to locate and move be- tween the infinitely many points on a map.§
A map is a map of some planet. (I say “planet” for simplicity’s sake, but my system will serve maps of moons, asteroids, and any other body that has latitude and longitude.) A map is an interesting part of my data set, but so is the actual planet it represents. It’s ‡Fun fact: prime meridians for planetary bodies are usually chosen by reference to some arbitrary feature like a crater. For bodies like Jupiter and Io, whose features are always changing, the prime meridian is defined according to which way the body was facing at an arbitrary time.
§A good reference for these algorithms is Ed Williams’s “Aviation Formulary” (http://williams.best.vwh.net/
convenient to refer to points on a planet, independent of any particular map, even though a planet doesn’t have physical lines of latitude and longitude running around it. One obvious use: I want to be able to see what maps there are for a particular point on Earth. There are probably more maps covering a point in New York City than a point in the middle of the Pacific Ocean.
So my data set includes not only the maps and the points on the maps, but the very planets themselves, and every point on the planets. It may seem hubristic to treat the entire planet Earth as a resource, but remember that I’m not obliged to give a complete account of the state of any resource. If my representation of “Earth” is just a list of my maps of Earth, that’s fine. The important thing is that the client can say “tell me about Earth,” as opposed to “tell me about the political map of Earth,” and I can give an answer.
Speaking of New York City and the Pacific Ocean, some points on a planet are more interesting than others. Most points have nothing much underneath them. Some points correspond to a cornfield or flat lunar plain, and others correspond to a city or a meteor crater. Some points on a planet are places. My users will be disproportionately inter- ested in these points on the planets, and the corresponding points on my maps. They won’t want to specify these places as latitude-longitude pairs. Indeed, many of my users will be trying to figure out where something is: they’ll be trying to turn a known place into a point on a planet.
Fortunately, most places have agreed-upon names, like “San Francisco,” “Eratos- thenes,” and “Mount Whitney.” To make it easy for my users to identify places, my data set will include a mapping of place names to the corresponding points on the planets.‖ Note that a single planet may have multiple places with the same name. There might be one “Joe’s Diner” on the Moon and a hundred on Earth, all distinct. If my user wants to find a particular Joe’s Diner on Earth, they’ll have to specify its location more precisely than just “Earth.”
What about places that aren’t points, like cities, countries, and rivers? For simplicity’s sake, I’ll make a well-chosen point stand for an area on a planet. For instance, I’ll have a point on Earth near the geographic center of the U.S. that stands for the place called “the United States of America.” (This is obviously a vast oversimplification. Many real GIS mapping programs represent such areas as lists of points, which form lines or polygons.)
Every place is of a certain type. Some places are cities, some mountains, some hot springs, some the current locations of ships, some areas of high pollution, and so on. I’ll keep track of the type of each place. Two places of different types may correspond
‖You may have a private name for a seemingly boring point on the map, like “the cornfield where I kissed Betty.” This will come into play in Chapter 6 when I expand my web service so that clients can create their own place names. For now, I’ve got a preset database of names for each planet.
to the same point on a planet: some unfortunate’s house may be built on top of a toxic waste dump.
My service can find a place on a planet, given its name, type, or description. It can show the place on any appropriate maps, and it can find places nearby. Given a street address, my service can locate the corresponding point on the planet Earth, and show it on a road map. Given the name of a country, it can locate the corresponding place on the planet (as a representative point), and show it on a political map.
If the client tries to find a place whose name is ambiguous (for instance, “Springfield”) my service can list all appropriate points within the given scope. The client will also be able to search for places of a certain type, without requiring the user give specific names. So a user can search for “pollution sites near Reno, Nevada.”