RESTful Feature APIs

Update (2007-04-10): a related demo.

Update: added examples of query results.

My previous post about WxS, RPC, and REST raised a few questions about whether queries fit into a RESTful GIS. The answer is: yes, queries remain indispensible. Indexes are a valuable part of your GIS, and a query API provides web agents access to the indexes.

Consider a very minimal municipal GIS which tracks properties, or parcels. Each parcel has many attributes, and the GIS indexes, at the very least, the following: a unique parcel id, the name of the parcel's owner, and the geospatial footprint of the parcel. These indexes allow a user to efficiently find all properties owned by an individual, or find all properties potentially impacted by construction along a particular path.

In a RESTful GIS, each parcel is a resource, and has a URL like:

http://example.org/parcels/[id]

Dereferencing the URL http://example.org/parcels/1 returns a representation, JSON in this case:

{ "id":       "1",
  "owner":    "Homer Simpson",
  "geometry": {
    "type":        "Polygon",
    "coordinates": [[...], ...] },
  ...
}

The "parcels" feature type is itself a resource. A useful representation of this resource would be a collection that includes URIs for, and data about, individual parcel resources -- all marshalled directly out of the GIS's indexes:

{ "parcels": [
  { "id": 1, "uri": "http://example.org/parcels/1",
    "owner": "Homer Simpson",
    "bbox": [1000.0, 1000.0, 1001.0, 1001.0] },
  { "id": 2, "uri": "http://example.org/parcels/2",
    "owner": "Ned Flanders",
    "bbox": [1001.0, 1001.0, 1002.0, 1002.0] },
  ...
  ]
}

That collection might easily include the precise footprints of properties, but we'll simply consider bounding boxes here.

A query API should return criteria-based subsets of that collection, leveraging the system's indexes. Which properties are going to be condemned to make way for the new monorail?:

GET /parcels/?bbox=0,0,2000,2000

The answer is: the parcels with URIs http://example.org/parcels/42 and http://example.org/parcels/83:

{ "parcels": [
  { "id": 42, "uri": "http://example.org/parcels/42",
    "owner": "Moe Szyslak",
    "bbox": [...] },
  { "id": 83, "uri": "http://example.org/parcels/83",
    "owner": "Kwik-E-Mart Corporation",
    "bbox": [...] }
  ]
}

Which properties are suffering catastrophic loss in value?:

GET /parcels/?adjacent(owner(Simpson))

The answer is: the parcel with URI http://example.org/parcels/2:

{ "parcels": [
  { "id": 2, "uri": "http://example.org/parcels/2",
    "owner": "Ned Flanders",
    "bbox": [...] }
  ]
}

The specific query parameters or URL templates to use are an implementation detail that I won't get into here (OpenSearch seems promising).

The gist of all this is that a RESTful feature query returns key, indexed data about feature resources along with a URI to the feature resources themselves in the same way that a Google Search returns data from its index, with links, instead of dumping the entire Web into your browser.