Planning RestAPI

Table of Contents Note, this work is done; this page for historical purposes only! Necessary REST API Features Desirable Qualities Legacy API Features (as of Dec 2010)

Note, this work is done; this page for historical purposes only!

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 <tt>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 http://en.wikipedia.org/wiki/Well-known_text|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":]
/api/map-browser/location-types/1/	GET	JSON representing all locations of location type 1. Example: [{"id":]
/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></place> or /api/newsitems.geojson/?schema=<slug></slug> or /api/newsitems.geojson/?nid=<newsitem></newsitem>	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>/&lt;location&#45;slug&gt;&lt;/location&#45;slug&gt&lt;/place.kml&gt;</type-slug>	GET	A single place (Block or Location), represented as http://en.wikipedia.org/wiki/Kml|KML