Necessary REST API Features

Our grant contract states:

"Query, export items, data, by location or other metadata
Push articles into system"

Extrapolating from that, we need at minimum:

• GET a list of NewsItems?, filtered by various criteria such as:
  • bounding box search
  • by schema type
  • within a Location (specified by ID)
  • by date ranges
  • by explicit NewsItem? IDs
• POST a new NewsItem?

We are anticipating that the POST API will largely supplant the need to write python ScraperScripts.

Other features that would very likely be useful:

• DELETE a NewsItem?
• GET a list of NewsItem? Schemas
• GET a list of Location Types
• GET a list of Locations
  • filter by LocationType?
  • bounding box or point intersection search?
• GET info about a Location
  • include WKT or GeoJSON boundaries
• Geocode an address

Desirable Qualities

• Always prefer URLs to opaque IDs in returned data. Be consistent.
• Rather than providing out-of-band documentation of rules for URL construction, just provide links in returned data, or maybe embed the rules as URI templates ( http://tools.ietf.org/html/draft-gregorio-uritemplate-04)
• Should allow cross domain access via CORS, get access via JSONP for older browser mashups
• API Keys?
• Use consistent output formats wherever applicable. Some candidates:
  • GeoRSS
  • Atom
  • GeoJSON
  • WKT or KML for representing boundaries

Legacy API Features (as of Dec 2010)

The ebpub package provides some views that are mostly targeted at usage via AJAX for javascript UI work. It's not really a formal API per se, but here are a few views that may be generally useful, and which overlap with some of the above desired features:

URL example	HTTP method	response
/api/wkt/?q=121+Main+st	GET	JSON, with a list of  WKT strings representing the geocoded result of the q argument (an address or location name).
/api/map-browser/location-types/	GET	JSON representing the types of locations in the system, e.g.: [{"plural_name": "neighborhoods", "id": 2, "slug": "neighborhoods"}, {"plural_name": "ZIP Codes", "id": 1, "slug": "zipcodes"}]
/api/map-browser/location-types/1/	GET	JSON representing all locations of location type 1. Example: [{"id": 1, "name": "02108", "slug": "02108"}, {"id": 2, "name": "02109", "slug": "02109"},...]
/api/map-browser/locations/1/	GET	JSON representing location id 1, including its name, its area (in what units?), its slug, its population (likely null), and WKT representing its boundaries. Example: {"name": "02108", "area": 1126876.6450880801, "wkt": "MULTIPOLYGON (((-71.0575149999999951 42.3611609999999956, ...", "slug": "02108", "centroid": "POINT (-71.0648038321608482 42.3570056252866962)", "normalized_name": "02108", "id": 1, "population": null}
/api/newsitems.geojson/ or /api/newsitems.geojson/?pid=<place id> or /api/newsitems.geojson/?schema=<slug> or /api/newsitems.geojson/?nid=<newsitem id>	GET	a JSON list of newsitems as   GeoJSON features, optionally filtered for one place ID and/or one schema slug, or one particular newsitem.
/locations/<type-slug>/<location-slug>/place.kml	GET	A single place (Block or Location), represented as  KML