SUBJETIVIDAD Y RECONOCIMIENTO DE LA MUJER EN EL ABORTO Debe comprenderse en primer lugar que la subjetividad en términos generales se

Are places really resources of their own or are they just alternate names for the “point on a planet” resources I just defined? After all, every place is just a geographic point. Maybe I’ve got a situation where a single resource has two names: one based on latitude and longitude, and one based on a human-readable name.

Well, consider a place representing the current location of a ship. It coincides with a specific point on the map, and it might be considered just an alternate name for that point. But in an hour, it’ll coincide with a different point on the map. A business, too, might move over time from one point on the map to another. A place in this service is not a location: it’s something that has location. A place has an independent life from the point on the map it occupies.

This is analogous to the discussion in Chapter 4 about whether “version 1.0.3” and “the latest version” point to the same resource. It may happen that they point to the same data right now, but there are two different things there, and each might be the target of a hypertext link. I might link to one and say “Version 1.0.3 has a bug.” I might link to the other and say “download the latest version.” Similarly, I might link to a point on Earth and say “The treasure is buried here.” Or I might link to a place called “USS

Mutiny” at the same coordinates and say “Our ship is currently here.” Places are their

own resources, and they’re resources of the second type: each one corresponds to an object exposed through the service.

I said earlier that place names are ambiguous. There are about 6,000 (an approxima- tion) cities and towns in the United States called Springfield. If a place name is unusual you can just say what planet it’s on, and it’s as good as specifying latitude and longitude. If a place name is common, you might have to specify more scoping information: giving a continent, country, or city along with the name of your place. Here are a few more sample resources:

• The Cleopatra crater on Venus • The Ubehebe crater on Earth

• 1005 Gravenstein Highway North, Sebastopol, CA • The headquarters of O’Reilly Media, Inc.

• The place called Springfield in Massachusetts, in the United States of America, on Earth

So far, this is pretty general stuff. Users want to know which maps we have, so we expose a one-off resource that lists the planets. Each planet is also a one-off resource that links to the available maps. A geographic point on a planet is addressable by lati- tude and longitude, so it makes sense to expose each point as an addressable resource. Every point on a planet corresponds to a point on one or more maps. Certain points are interesting and have names, so places on a planet are also accessible by name: a client can find them on the planet and then see that point on a map.

All I’ve done so far is describe the interactions between parts of a predefined data set. I haven’t yet exposed any algorithmically-generated resources, but it’s easy enough to add some. The most common kind of algorithmic resource is the list of search results. I’ll allow my clients to search for places on a planet that have certain names, or that match place-specific criteria. Here are some sample algorithmic resources:

• Places on Earth called Springfield • Container ships on Earth

• Craters on Mars more than 1 km in diameter • Places on the moon named before 1900

Search results can be restricted to a particular area, not just a planet. Some more sample resources:

• Places in the United States named Springfield • Sites of hot springs in Colorado

• Oil tankers or container ships near Indonesia • Pizza restaurants in Worcester, MA

• Diners near Mount Rushmore

• Areas of high arsenic near 24.9195N 17.821E • Towns in France with population less than 1,000

These are all algorithmically-generated resources, because they rely on the client pro- viding an arbitrary search string (“Springfield”) or combining unrelated elements (“Mount Rushmore” + diners, or “France” + towns + “population < 1000”).

I could come up with new kinds of resources all day (in fact, that’s what I did while writing this). But all the resources I’ve thought up so far fit into five basic types, just enough to make the fantasy interesting. Example 5-1 gives the master list of resource types.

Example 5-1. The five types of resources 1. The list of planets

2. A place on a planet—possibly the entire planet—identified by name 3. A geographic point on a planet, identified by latitude and longitude 4. A list of places on a planet that match some search criteria

5. A map of a planet, centered around a particular point

A real-life web service might define additional resources. Real web sites like Google Maps expose one obvious bit of functionality I haven’t mentioned: driving directions. If I wanted to enhance my service I might expose a new algorithmically-generated re- source which treats a set of driving directions as a relationship between two places. The

representation of this resource might be a list of textual instructions, with references to points on a road map.

General Lessons

A RESTful web service exposes both its data and its algorithms through resources. There’s usually a hierarchy that starts out small and branches out into infinitely many leaf nodes. The list of planets contains the planets, which contain points and places, which contain maps. The S3 bucket list contains the individual buckets, which contain the objects.

It takes a while to get the hang of exposing an algorithm as a set of resources. Instead of thinking in terms of actions (“do a search for places on the map”), you need to think in terms of the results of that action (“the list of places on the map matching a search criteria”). You may find yourself coming back to this step if you find that your design doesn’t fit HTTP’s uniform interface.