API Documentation
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.
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:
- A JSON file storage on the local file system
- A MongoDB database
- A Socket.io connection
- A MQTT connection
- The HTTP 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. |
A swagger documentation page is maintained at localhost:3002/swagger/.
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.