Revision as of 17:31, 5 June 2013

HyperCities exposes a RESTful API for viewing and editing objects, collections, maps, and cities. In REST, a webservice provides access to “resources”, or data items. Each resource can be accessed at a unique URL. Accessing and editing a resource are accomplished using different HTTP methods such as GET or POST. Each of these resources usually fall into a few different categories, and a web service may have many items in many categories. The last isn’t necessarily part of the formal definition of REST, but it’s a convention used in most RESTful services.

REST verbs

In REST, a separate HTTP verb (GET, POST, PUT, and DELETE) performs each action. You can probably guess what each one does, except for POST and PUT. There is disagreement on whether POST should create and PUT should update, or vice versa. HyperCities uses the following scheme:

We do not use PUT because PUT is difficult to implement, especially in a browser, and its functions can be equally implemented by POST.

When you update a resource, you must supply all attributes of the resource for every request. Missing attributes will be erased or set to default values if they are not supplied, or result in validation errors. Think about each resource as a file, not a collection of attributes: you always have to send the whole back, not just the changes. There are different ways of specifying the format in which data should be returned in REST. Some services use Accept headers; others user file extensions (e.g. /maps/1.json). Both have tradeoffs. HyperCities exclusively uses extensions for simplicity and the fact that it uses some nonstandard formats, like KML, which have to be produced for geobrowsers that might not send correct headers. It involves less debugging to give your users a URL to copy and paste that is guaranteed to return the correct format.

Resource types

HyperCities has three kinds of resources: rich objects, collections, and maps.

• Rich objects are any kind of item you see on the map, with the exception of historical maps; maps are distinguished from rich objects because all major mapping APIs (Google Maps, Google Earth, OpenLayers, Leaflet, Polymaps, and the like) differentiate between clickable items on the map, and additional tiles overlaid on the map.
• Collections are ordered sets of rich objects, which are frequently used to form narratives. While collections and rich objects are accessed through different URLs (/objects and /collections, respectively), they are stored in the same database tables as they are part of the same hierarchy--an object belongs to one (or more) collections, and can contain one or more objects and collections itself (we’ll cover this later).
• Maps are tiled images overlaid on the main HyperCities map.

Rich objects, maps, and collections can be exposed in JSON formats. This JSON format is custom for HyperCities, not a standard like GeoJSON. Rich objects and collections are also available as KML. The details of these formats are all documented in the links above.

Response types

Attempting to create, delete, or update any kind of resource will usually return one of the following responses: