The HyperCities API
Davidshepard (Talk | contribs) (Created page with "HyperCities exposes a RESTful API for viewing and editing its objects.") |
Davidshepard (Talk | contribs) |
||
| Line 1: | Line 1: | ||
| − | HyperCities exposes a [ | + | HyperCities exposes a [http://en.wikipedia.org/wiki/Representational_state_transfer 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. |
| + | |||
| + | HyperCities has three (or four) kinds of resources, depending on how you look at it. These are rich objects, collections, maps, and cities. | ||
| + | * '''[[Rich Objects API|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. | ||
| + | * '''[[Maps API|Maps]]''' are tiled images overlaid on the main HyperCities map. | ||
| + | * '''[[Collections API|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). | ||
| + | * '''[[Cities API:Cities]]''' are probably the least important resource; they are mostly a navigational aid for visitors to find where we have content. You can implement a full-featured HyperCities viewer without worrying about them. | ||
| + | |||
| + | 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. These are all documented in the links above. | ||
Revision as of 10:50, 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.
HyperCities has three (or four) kinds of resources, depending on how you look at it. These are rich objects, collections, maps, and cities.
- 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.
- Maps are tiled images overlaid on the main HyperCities 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).
- Cities API:Cities are probably the least important resource; they are mostly a navigational aid for visitors to find where we have content. You can implement a full-featured HyperCities viewer without worrying about them.
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. These are all documented in the links above.
