API Documentation

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 by making use of the infrastructure already in place.

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. In general this means that the verb used by the request specifies the nature of the action. However, sometimes it is not desireable to use the correct verb - e.g. using get when a large amount of variables need to be passed to the server.

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
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
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

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.