21.1.2017

API

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

Media service

ListVgiMedia

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

InsertVgiMedia

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

UpdateVgiMedia

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

GetVgiMedia

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

DeleteVgiMedia

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