Skip to content
jeffluppes edited this page Aug 20, 2015 · 2 revisions

Common Sense API

This is the documentation page for the Common Sense API. The API is a work in progress and is being developed in the development-api branch. The API accepts GeoJSON only.

Internal structure

The API has been designed in such a way that it should be easy to add new storage or communication modules.

The modules are This will make it possible to broadcast changes via Socket.io or Mqtt as they are being made to JSON files on your local machine. You can also load layers from MongoDB as you update them via the HTTP interface. At this time the following modules are being developed:

  1. A JSON file storage on the local file system
  2. A MongoDB database
  3. A Socket.io connection
  4. A MQTT connection
  5. The HTTP interface


HTTP RESTful interface

The HTTP interface is built using Express and where possible, implements RESTful pathing using HTTP verbs.

Verb Action
get Retrieving a resource or result
post Inserting new information
put Replace or Update operations
delete Removal operations

The base path with all routes is /api. This means that in order to obtain a list of all layers a get request can be sent to (assuming a local machine and port 3002) localhost:3002/api/layers/. Please note that the swagger documentation has much more details about parameters, schema, and possible server responses.

Layers

Verb Path Description
delete /layers/{layerId} Delete a layer by ID
get /layers/{layerId} Find layer by ID
put /layers/{layerId} Update an existing layer
get /layers/ Returns a list of all layers and their associated storage engine
post /layers/ Add a new layer to the system

Features

Verb Path Description
delete /layers/{layerId}/feature/{featureId} Delete a feature by ID
get /layers/{layerId}/feature/{featureId Find feature by ID
put /layers/{layerId}/feature/{featureId} Update a single pre-existing feature
post /layers/{layerId}/feature Adds a feature

Log manipulation

Verb Path Description
delete /layers/{layerId}/{featureId}/log Delete a log by supplying timestamp, value, and IDs
get /layers/{layerId}/{featureId}/log Find the log file associated with a single feature
put /layers/{layerId}/{featureId}/log Adds a log to a feature by updating it with a log

Special methods

Note: at the moment these are only available when using the MongoDB storage option

Verb Path Description
get /layers/{layerId}/bbox Gets all and any points in a (bounding box) rectangle.
get /layers/{layerId}/getsphere Gets all and any points in a sphere defined by its center coordinate.
get /layers/{layerId}/getwithinpolygon Gets all and any points that are within a user-supplied polygon in a GeoJSON document.

Swagger documentation

A swagger documentation page is maintained at localhost:3002/swagger/.

Adding your own Swagger documentation

Swagger enables developers to add documentation about their web APIs. At current this is not an automated process: you will have to supply a small amount of information about the paths you have added. Fortunately this is not an arduous activity. The Swagger.JSON file is editable with any text editor in addition to the Swagger editor which supports both YAML and JSON.