The HyperCities API

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:

HTTP Method	URL	Description
GET	/{resource type}	search for resources of that type
GET	/{resource_type}/{id}	get one resource
POST	/{resource_type}	create a new resource of that type
POST	/{resource_type}/{id}	update an existing resource
DELETE	/{resource_type}/{id}	delete that resource

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:

HTTP Code	Message	Meaning
201	Object Created	The object was successfully created.
202	Object Updated	Object was successfully updated
400	Bad Request	Values supplied for the object were either incomplete or invalid.
401	Insufficient Privileges	The current user is not allowed to edit this resource. (Also, the user may not be logged in.)
404	Not Found	The object was not found.