SensLog contains RESTful API for Feeder, Provider, VGI and Telemetry module. Most important services and methods will be described in following tables.
Controller Servlet
Controller servlet allows to login to SensLog and to send further requests.
| URL |
| /ControllerServlet |
| Method |
Functionality |
Format |
| POST |
Request provides users to login to the SensLog |
KVP text/plain |
| Parameter |
Format |
Role |
| username |
text/plain |
Username of current user |
| password |
text/plain |
Password of current user |
Important notes:
HTTP Post request has to contain a Header with value:
Content-Type: application/x-www-form-urlencoded
Example of payload:
username=test&password=demo
Example of correct response:
{"sessionid":"rv6pe5o30091","language":"en","audio":"false"}
Example of HTTP Header Cookie to be added to any further requests:
Cookie: JSESSIONID=rv6pe5o30091; sessionid=rv6pe5o30091; language=en; audio=false
Feeder Servlet
Feeder Servlet allows to insert observations, units positions and alerts.
| URL |
| /FeederServlet?Operation=operationName |
| Method |
Functionality |
Format |
| GET |
Provides insertion of main collected objects |
URL encoded text/plain |
InsertObservation
| URL |
| /FeederServlet?Operation=InsertObservation |
| Method |
Functionality |
Format |
| GET |
Provides inserting of new observation for combination of sensor and unit into database. Return true if observation was successfully inserted, false in all other cases. |
URL encoded text/plain |
| Parameter |
Format |
Role |
| value |
Double precision |
Measured value (mandatory) |
| date |
Time stamp (ISO 8601) |
Timestamp of measured value (e.g. 2015-07-15 12:00:00+0200) (mandatory) |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
| sensor_id |
Numerical value |
Identifier of sensor (mandatory) |
InsertPosition
| URL |
| /FeederServlet?Operation=InsertPosition |
| Method |
Functionality |
Format |
| GET |
Provides inserting of new unit position in the database, position can be inserted only as WGS-84 coordinates. Return true if position was inserted successfully, false in all other cases. |
URL encoded text/plain |
| Parameter |
Format |
Role |
| lat |
Double precision |
Latitude (mandatory) |
| lon |
Double precision |
Longitude (mandatory) |
| alt |
Double precision |
Altitude in meters (optional) |
| speed |
Double precision |
Speed of the unit (optional) |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
| date |
Timestamp (ISO 8601) |
Timestamp of measured value (e.g. 2015-07-15 12:00:00+0200) (mandatory) |
| dop |
Numerical value |
Dilution of precision (optional) |
InsertAlertEvent
| URL |
| /FeederServlet?Operation=InsertAlertEvent |
| Method |
Functionality |
Format |
| GET |
Provides inserting of new alert event that was detected in the sensor network into database, Return true if event was successfully inserted, false in all other cases. |
URL encoded text/plain |
| Parameter |
Format |
Role |
| alert_id |
Numerical value |
Identifier of alert (mandatory) |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
| date |
Timestamp (ISO 8601) |
Timestamp of measured value (e.g. 2015-07-15 12:00:00+0200) (mandatory) |
Data Service
Data Service provides information about units and positions of units
| URL |
| /DataService?Operation=operationName |
| Method |
Functionality |
Format |
| GET |
Provides detailed information about sensor units |
JSON |
GetUnits
| URL |
| /DataService?Operation=GetUnits |
| Method |
Functionality |
Format |
| GET |
Provides detailed information about each units connected to login user. Response contains connected sensors, first and last time stamp of entered observation, last positions of units. |
JSON |
GetUnitsList
| URL |
| /DataService?Operation=GetUnitsList |
| Method |
Functionality |
Format |
| GET |
Provides basic information about each units connected to login user. Response contains identifier of each unit and its description. |
JSON |
GetPositions
| URL |
| /DataService?Operation=GetPositions |
| Method |
Functionality |
Format |
| GET |
Request provides users specified number of last positions of all units in current group. |
JSON |
| Parameter |
Format |
Role |
| user |
Text |
Identifier of user group |
| limit |
Numeric value |
Number of positions to receive |
GetPositionsDay
| URL |
| /DataService?Operation=GetPositionsDay |
| Method |
Functionality |
Format |
| GET |
Request provides list of positions of specified unit during given time range. Positions can be ordered by timestamp ascending or descending. This method is variable to GetTracks, but providing raw positions as Points rather than tracks as Polylines. |
JSON |
| Parameter |
Format |
Role |
| user |
Text |
Identifier of user group. (mandatory) |
| unit_id |
Numeric value |
Identifier of unit. (mandatory) |
| fromTime |
Date (ISO 8601) |
Beginning date of the time range. (optional) |
| toTime |
Date (ISO 8601) |
End date of the time range. (optional) |
| ordering |
Text |
Identifier of ordering way. Only values “ascending” and “descending” are allowed. (optional) |
GetLastPositions
| URL |
| /DataService?Operation=GetLastPositions |
| Method |
Functionality |
Format |
| GET |
Request provides user last positions of all units in user group. |
JSON |
GetLastPositionsWithStatus
| URL |
| /DataService?Operation=GetLastPositionsWithStatus |
| Method |
Functionality |
Format |
| GET |
Request provides user information about alert events and other attributes in addition to previous GetLastPositions request. |
JSON |
GetTracks
| URL |
| /DataService?Operation=GetTracks |
| Method |
Functionality |
Format |
| GET |
Request returns entered number of trajectory geometries of all moving units in user group. |
URL encoded text/plain |
| Parameter |
Format |
Role |
| limit |
Numerical value |
Number of tracks to receive |
GetRecentTracks
| URL |
| /DataService?Operation=GetRecentTracks |
| Method |
Functionality |
Format |
| GET |
Request returns trajectory geometries of all moving units in user group. |
URL encoded text/plain |
Sensor Service
SensorService provides information about sensors and enables to get measured or processed data.
| URL |
| /SensorService?Operation=operationName |
| Method |
Functionality |
Format |
| GET |
Provides detailed information about sensors and provides methods to get sensor data. |
JSON |
GetSensors
| URL |
| /SensorService?Operation=GetSensors |
| Method |
Functionality |
Format |
| GET |
Request returns list of sensors connected to entered unit. |
JSON |
| Parameter |
Format |
Role |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
GetObservations
| URL |
| /SensorService?Operation=GetObservations |
| Method |
Functionality |
Format |
| GET |
Request provides access to measured or processed observations for entered unit-sensor pair and entered time range. If user doesn’t enter time range, servlet returns all available observations for entered unit-sensor pair. Another optional parameter is trunc that executes average of values for entered epoch (hour, day, week,…). |
JSON |
| Parameter |
Format |
Role |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
| sensor_id |
Numerical value |
Identifier of sensor (mandatory) |
| from |
Timestamp (ISO 8601) |
Time stamp of beginning time range (optional) |
| to |
Timestamp (ISO 8601) |
Time stamp of end time range (optional) |
| trunc |
Text |
Average epoch (optional) |
GetLastObservations
| URL |
| /SensorService?Operation=GetLastObservations |
| Method |
Functionality |
Format |
| GET |
Provides last observations of specified unit or group of units. Returns JSON with observations. |
JSON |
| Parameter |
Format |
Role |
| group |
Textual value |
Name of group of units (optional), alone or with sensor_id |
| unit_id |
Numerical value |
Identifier of unit (optional), alone or with sensor_id |
| sensor_id |
Numerical value |
Identifier of sensor (optional) |
GetLastObservations – allowed combinations
- &group=
- &group=&sensor_id=
- &unit_id=
- &unit_id=&sensor_id=
AlertService
AlertService provides information about alerts events that arrived in sensor network. Methods allow user to get description of potential alerts connected to specific unit and list of arrived alert events including solving state.
| URL |
| /AlertService?Operation=operationName |
| Method |
Functionality |
Format |
| GET |
Provides information about alerts events that arrived in sensor network. |
JSON |
GetAlerts
| URL |
| /AlertService?Operation=GetAlerts |
| Method |
Functionality |
Format |
| GET |
Request provides list of potential alerts for entered unit. |
JSON |
| Parameter |
Format |
Role |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
GetAlertEventsByTime
| URL |
| /AlertService?Operation=GetAlertEventsByTime |
| Method |
Functionality |
Format |
| GET |
Request provides list of arrived alert events for specified unit and specified time range. |
JSON |
| Parameter |
Format |
Role |
| unit_id |
Numerical value |
Identifier of unit (mandatory) |
| from |
Timestamp (ISO 8601) |
Time stamp of beginning time range (optional) |
| to |
Timestamp (ISO 8601) |
Time stamp of end time range (optional) |
ManagementService
ManagementService allows user to register unit with sensors. This service is especially suitable for scenario “collecting data by smartphones”, it enables register new smartphone before starting of collecting data.
| URL |
| /ManagementService?Operation=operationName |
| Method |
Functionality |
Format |
| POST |
Provides registration of new components of sensor network |
JSON |
InsertUnit
| URL |
| /ManagementService?Operation=InsertUnit |
| Method |
Functionality |
Format |
| POST |
Provides insertion of new unit with sensors into database. Returns JSON description of the unit with IDs of unit, sensors and phenomenons. |
JSON |
Example of InsertUnit payload
{
"unit":{
"description":"test insert unit"
},
"sensors":[
{
"sensor_name":"test sensor1",
"sensor_type":"testing sensor",
"phenomenon":{
"phenomenon_name":"testing phenomenon 1",
"uom":"rounds"
}
},
{
"sensor_name":"test sensor 2",
"sensor_type":"testing sensor",
"phenomenon":{
"phenomenon_name":"testing phenomenon 2",
"uom":"points"
}
}
]
}
VGI module
SensLog API for VGI has been improved during last months. Services and methods were added to meet most of CRUD schema (Create, Retrieve, Update, Delete) of REST services. Other methods will be added during next development.
VgiObservationService
VGI service alllows to insert new POI, update stored POI, to select POIs by several filters and to add, select, update or delete categories and datasets.
InsertVgiObservation
| URL |
| /rest/vgi/observation |
| Method |
Functionality |
Format |
| POST |
Provides insertion or update of POI into database. Returns ID of inserted POI, or true if POI was updated. |
Content-Type: multipart/form-data
Result: text/plain
|
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
Identifier of POI, optional |
| time_stamp |
Textual value |
Timestamp when POI was observed (ISO 8601 compatible), mandatory |
| category_id |
Numerical value |
Identifier of category, mandatory |
| description |
Textual value |
Free text description of POI, optional |
| attributes |
Textual value |
JSON formated additional attributes, optional |
| dataset_id |
Numerical value |
Identifier of dataset, optional |
| unit_id |
Numerical value |
Identifier of device producing POI, mandatory |
| lon |
Numerical value |
Longitude of POI, mandatory |
| lat |
Numerical value |
Latitude of POI, mandatory |
| alt |
Numerical value |
Altitude of POI, optional |
| dop |
Numerical value |
Dilution of precision of position, optional |
| media |
File |
Connected media file, optional |
| media_type |
Textual value |
Name of media type (MIME) of connected file, mandatory if media file is presented |
UpdateVgiObservation
| URL |
| /rest/vgi/observation/{obs_vgi_id} |
| Method |
Functionality |
Format |
| PUT |
Provides update of POI into database. Returns true if POI was updated. |
text/plain |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
Identifier of POI to be updated, mandatory |
| time_stamp |
Textual value |
Timestamp when POI was observed (ISO 8601 compatible), mandatory |
| category_id |
Numerical value |
Identifier of category, mandatory |
| description |
Textual value |
Free text description of POI, optional |
| attributes |
Textual value |
JSON formated additional attributes, optional |
| dataset_id |
Numerical value |
Identifier of dataset, optional |
| unit_id |
Numerical value |
Identifier of device producing POI, mandatory |
| lon |
Numerical value |
Longitude of POI, mandatory |
| lat |
Numerical value |
Latitude of POI, mandatory |
| alt |
Numerical value |
Altitude of POI, optional |
| dop |
Numerical value |
Dilution of precision of position, optional |
| media |
File |
Connected media file, optional |
| media_type |
Textual value |
Name of media type of connected file, mandatory if media file is presented |
SelectVgiObservations
| URL |
| /rest/vgi/observation/ |
| Method |
Functionality |
Format |
| GET |
Service provides stored POIs in JSON or GeoJSON format by given filters. |
JSON, GeoJSON |
| Parameter |
Format |
Role |
| user_name |
Textual value |
Name of user that collects POIs, only own user_name or user_name from same group allowed, mandatory |
| format |
Textual value |
Name of output format (geojson, json allowed), optional |
| dataset_id |
Numerical value |
ID of dataset, optional |
| category_id |
Numerical value |
ID of category, optional |
| extent |
Textual value |
Description of extent in format: [Xmin, Ymin, Xmax, Ymax, SRID], optional |
| from_time |
Textual value |
Begin timestamp of frame, optional |
| to_time |
Textual value |
End timestamp of frame, optional |
SelectVgiObservation
| URL |
| /rest/vgi/observation/{obs_vgi_id} |
| Method |
Functionality |
Format |
| GET |
Service provides stored POI in JSON or GeoJSON format by given ID. |
JSON, GeoJSON |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of VgiObservation to be selected, mandatory |
| user_name |
Textual value |
Name of user that collects POIs, only own user_name or user_name from same group allowed, mandatory |
| format |
Textual value |
Name of output format (geojson, json allowed), optional |
DeleteVgiObservation
| URL |
| /rest/vgi/observation/{obs_vgi_id} |
| Method |
Functionality |
Format |
| DELETE |
Service provides deleting of stored POI by given ID. |
text/plain |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of VgiObservation to be selected, mandatory |
| user_name |
Textual value |
Name of user that collects POIs, only own user_name or user_name from same group allowed, mandatory |
| URL |
| /rest/vgi/observation/{obs_vgi_id}/media |
| Method |
Functionality |
Format |
| GET |
Provides list of stored POI media |
JSON |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of POI |
| user_name |
Textual value |
Name of user |
| URL |
| /rest/vgi/observation/{obs_vgi_id}/media |
| Method |
Functionality |
Consume format |
| POST |
Provides storing of new POI media |
multipart/form-data; charset=UTF-8 |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of POI, mandatory |
| media |
File |
Connected media file, mandatory |
| media_type |
Textual value |
Name of media type of connected file, mandatory if media file is presented |
| URL |
| /rest/vgi/observation/{obs_vgi_id}/media/{media_id} |
| Method |
Functionality |
Consume format |
| PUT |
Provides update of new POI media |
multipart/form-data; charset=UTF-8 |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of POI, mandatory |
| media_id |
Numerical value |
ID of VgiMedia file, mandatory |
| media |
File |
Connected media file, mandatory |
| media_type |
Textual value |
Name of media type of connected file, mandatory if media file is presented |
| URL |
| /rest/vgi/observation/{obs_vgi_id}/media/{media_id} |
| Method |
Functionality |
Format |
| GET |
Provides stored POI media file |
Depends on media type of stored file |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of POI |
| media_id |
Numerical value |
ID of specific VgiMedia file |
| user_name |
Textual value |
Name of user |
| URL |
| /rest/vgi/observation/{obs_vgi_id}/media/{media_id} |
| Method |
Functionality |
Format |
| DELETE |
Provides delete operation of selected POI media file |
text/plain |
| Parameter |
Format |
Role |
| obs_vgi_id |
Numerical value |
ID of POI |
| media_id |
Numerical value |
ID of specific VgiMedia file |
| user_name |
Textual value |
Name of user |
VGICategory service
SelectVgiCategories
| URL |
| /rest/vgi/category/ |
| Method |
Functionality |
Format |
| GET |
Provides stored categories of POIS |
JSON |
SelectVgiCategory
| URL |
| /rest/vgi/category/{category_id} |
| Method |
Functionality |
Format |
| GET |
Provides stored categories of POIS |
JSON |
| Parameter |
Format |
Role |
| category_id |
Numerical value |
ID of category |
| user_name |
Textual value |
Name of user |
SelectVgiCategory descendants
| URL |
| /rest/vgi/category/{category_id}/descendants |
| Method |
Functionality |
Format |
| GET |
Provides list of stored categories of POIs |
JSON |
| Parameter |
Format |
Role |
| category_id |
Numerical value |
ID of category |
| user_name |
Textual value |
Name of user |
VgiDatasetService
SelectVgiDatasets
| URL |
| /rest/vgi/dataset/ |
| Method |
Functionality |
Format |
| GET |
Provides list of stored datasets of POIs |
JSON |
| Parameter |
Format |
Role |
| user_name |
Textual value |
Name of user |
InsertVgiDataset
| URL |
| /rest/vgi/dataset/ |
| Method |
Functionality |
Consume format |
| POST |
Provides insertion of new dataset of POIs |
application/json; charset=utf-8 |
| Parameter |
Format |
Role |
| user_name |
Textual value |
Name of user |
GetVgiDataset
| URL |
| /rest/vgi/dataset/{dataset_id} |
| Method |
Functionality |
Format |
| GET |
Provides select of specific dataset of POIs |
application/json; charset=utf-8 |
| Parameter |
Format |
Role |
| dataset_id |
Numerical value |
ID of dataset |
| user_name |
Textual value |
Name of user |
DeleteVgiDataset
| URL |
| /rest/vgi/dataset/{dataset_id} |
| Method |
Functionality |
Format |
| DELETE |
Provides deletion of specific dataset of POIs |
text/plain |
| Parameter |
Format |
Role |
| dataset_id |
Numerical value |
ID of dataset |
| user_name |
Textual value |
Name of user |
Last update: 14th February 2017