One can get started to use our system by following the steps in the user manual (see section 3) and then can start using the Gadgeteer library to make use of the functionalities offered by this system. But to get started with API services, there are few important steps to be followed. First a device has to send a registration message to the web service to indicate that it started to work and then use data logging API to send data. After logging data, one can use the data retrieval API to get the data from the cloud.
Each device has to go through two step procedure to register to our system. Firstly, the user should create the device from our website. Secondly, a registration message has to be sent from the device along with the list of sensors that are embedded in the device. This step is important to acquire unique IDs for each of the sensors within a device. The sensor names within a device should be unique. This HTTP message should contain an Authorization Header with value “APIKey {APIKEY of device}”. This API Key will be used to check the authenticity of the registration message. During registration, each sensor should possess a value for the following fields.
After a device is registered with all the associated sensors in it, the device can start logging data. This process is very simple. The data logging API is designed to accept any payload as long as the HTTP body is in the following format.
{
"sensorId":2147483647,
"deviceId":2147483647,
"data":[{ JSON}, {JSON}]
}
It is mandatory to include the ‘sensorId’ and ‘deviceId’ in the body of the request message. The ‘data’ attribute can take valid JSON value. For example:
“data” :[{ “temperature”:23.45,”at”:”23/08/2013 22:56:34”}, {“temperature”:23.45,”at”:”23/08/2013 22:58:34”}]
This data will be stored in the Mongo DB as JSON documents and can be retrieved as such later. Also, near real time push notifications can be received by subscribing to this sensor through subscribe API.
The data that is logged from the device can be retrieved in two ways .One by subscribing to the pusher channel to receive live push notifications and other way by retrieving already stored data from the database. To retrieve stored (historic) data from the cloud, we have followed a new process to retrieve data by pages since the required data can be huge. Therefore, the user of this API should define a page size (number of JSON records) in each request. First ‘sensordata/paeginfo’ API should be invoked with valid start and end datetime. The response of this message will be list of URIs which will retrieve the actual data from the cloud. Just loop through the response and invoke each URI inside the list to aggregate the entire required data.
Apart from the APIs mentioned in the above sections, this system has other APIs which are heart to user and device management as well as other functionalities. When a developer wants to make use of our API, it is important that he/she understands the interface structure and functionality provided. For this purpose, we have documented all the exposed APIs.
Resource |
Uri |
Method |
Description |
Request Body |
Response Body |
|
DataLogging.svc/ |
||||||
Data Logging |
logData
Content Type: application/octet-stream |
POST |
Logs data from a device |
{ "sensorId":2147483647, "deviceId":2147483647, "data":[{ JSON}, {JSON}] } |
Success |
|
Notification
Content Type: application/json |
POST |
Notifies an event |
{ "deviceId":2147483647, "reason":"String content", "sensorId":2147483647, "userId":2147483647 } |
Success |
||
Chart.svc/ |
||||||
Data Retrieval |
sensordata/ paeginfo?
userid={USERID}&sensorid={SENSORID}&start={START}&end={END}&pagesize={PAGESIZE}
|
GET |
Get the pages of historic Data. Contains list of Uri’s from which data can be retrieved based on fixed page size (no. of records). E.g. START: 14/05/2013 11:20:44 END: 15/05/2013 11:20:44 |
-NA- |
{ "PageData": [ "http:\\www.example.com\pagedata?userid={USERID}&sensorid={SENSORID}&start={START}&end={END}&pagesize={PAGESIZE}",
”http:\\www.example.com\pagedata?userid={USERID}&sensorid={SENSORID}&start={START}&end={END}&pagesize={PAGESIZE}” ] } |
|
sensordata/ pagedata?
suserid={USERID}&sensorid={SENSORID}&start={START}&end={END}&pagesize={PAGESIZE} |
GET |
Retrieves the actual data of the device. This url is embedded in the response of “sensordata/ Paeginfo” |
-NA- |
{ "sensorId":2147483647, "deviceId":2147483647, "data":"String content" } |
||
Devices.svc/ |
||||||
Device Registration |
device
Authorization Header: APIKey {APIKEY}
Content Type: application/json |
POST |
Registers all the sensors of a device. A device can have any no. of sensor, e.g. temperature, barometer. All these sensors should be registered with a unique id. |
{ "DeviceId":2147483647, "Sensors":[{ "Fault_tolerance":2147483647, "Interval_measure":"String content", "Interval_send":"String content", "Make":"String content", "Metadata":"String content", "Name":"String content", "Type":"String content" }] } |
Success |
|
sUsers.svc/ |
||||||
User |
user
Content Type: application/json |
POST |
Adds a user |
{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Password":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" }
|
{ "href":"http:\\www.example.com\Services\users.svc\user\{userid}", "response":{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" } } |
|
user/{USERID}
|
GET |
Gets the details of a user |
-NA- |
{ "href":"http:\\www.example.com\Services\users.svc\user\{userid}", "response":{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" } } |
||
user/update/ { USERID }
Content Type: application/json |
POST |
Updates the user – User id and username are mandatory in the request body for identification and authentication |
{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" }
|
{ "href":"http:\\www.example.com\Services\users.svc\user\{userid}", "response":{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" } } |
||
user/delete/ { USERID } Content Type: application/json |
POST |
Deletes a user |
{ "Id":2147483647, "Password":"String content" } |
true
|
||
user/login
Content Type: application/json |
POST |
Logins a user |
{ "Password":"String content", "Username":"String content" }
|
{ "href":"http:\\www.example.com\Services\users.svc\user\{userid}", "response":{ "Country":"String content", "EmailAddress":"String content", "FirstName":"String content", "Id":2147483647, "LastName":"String content", "Organization":"String content", "Purpose":"String content", "Title":"String content", "Username":"String content" } }
|
||
user/ changepassword/{ USERID } Content Type: application/json |
POST |
Changes user password |
{ "Id":2147483647, "NewPassword":"String content", "OldPassword":"String content" } |
true |
||
users/ checkusername/{USERNAME}
|
GET |
Checks if unique username is available |
-NA-
|
true |
||
device |
devices ?userid={USERID}&deviceid={DEVICEID}
|
GET |
Gets the specified device provided a valid USERID who is authorized to access the given DEVICEID |
-NA- |
{ "href":"http:\\www.example.com\Services\devices\device?userid={userid}&deviceid={deviceid}", "response":{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 } } |
|
devices
Content Type: application/json |
POST |
Adds a device |
{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 }
|
{ "href":"http:\\www.example.com\Services\devices\device?userid={userid}&deviceid={deviceid}", "response":{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 } } |
||
devices/list ?userid={USERID}&privacy={PRIVACY}
|
GET |
Gets a list of devices for a given userid and specified privacy level. Privacy can take the following values: “public, private, shared and all”. ‘all’ retrieves all private and public devices |
-NA- |
[{ "href":"http:\\www.example.com\Services\devices\device?userid={userid}&deviceid={deviceid}", "response":{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 } }] |
||
devices/ update/ { DEVICEID }
Content Type: application/json |
POST |
Updates a device |
{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 }
|
{ "href":"http:\\www.example.com\Services\devices\device?userid={userid}&deviceid={deviceid}", "response":{ "APIKey":"String content", "Confirmation_date":"\/Date(928149600000+0000)\/", "Confirmed":true, "Connection_string":"String content", "Creation_date":"\/Date(928149600000+0000)\/", "Db_name":"String content", "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content", "Privacy":"String content", "Status":true, "User_id":2147483647 } } |
||
devices/ delete/ { DEVICEID } Content Type: application/json |
POST |
Deletes a device |
-NA- |
true
|
||
devices/ checkdevicename ?userid={USERID}&devicename={DEVICENAME} |
GET |
Checks if a given DEVICENAME is unique device name under USERID |
-NA- |
true |
||
lostdevices/ { USERID }
|
GET |
Get the list of lost devices |
-NA- |
[{ "deviceId":2147483647, "deviceName":"String content", "notificationId":2147483647, "reason":"String content", "sensorId":2147483647 }] |
||
sharedevice/ { DEVICEID } Content Type: application/json |
POST |
Adds a private device to be shared with another user |
{ "OwnerId":2147483647, "SharerUsername":"String content" } |
true |
||
sharedevice/ delete/ { DEVICEID } Content Type: application/json |
POST |
Delets a private device shared with another user |
{ "OwnerId":2147483647, "SharerUsername":"String content" } |
true |
||
customrepo/ device/ { DEVICEID }
|
GET |
gets the repository where data is stored |
-NA- |
{ "DBName":"String content", "Id":2147483647, "Port":2147483647, "Url":"String content" } |
||
customrepo/ device/ { DEVICEID }
Content Type: application/json |
POST |
Change the repository to store data |
{ "DBName":"String content", "Id":2147483647, "Port":2147483647, "Url":"String content" } |
Success |
||
subscribe ?sensorid={SENSORID}&userid={USERID}
|
GET |
Subscribe to particular SENSORID by providing USERID of who wants to subscribe. |
-NA- |
{ "Channel":"String content", "Event":"String content", "Key":"String content" }
|
||
publicdevices/ { USERID }
|
GET |
Gets all the authorized devices |
-NA- |
{ "Private":[{ "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content" }], "Public":[{ "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content" }], "Shared":[{ "Description":"String content", "Id":2147483647, "Ip":"String content", "Location":"String content", "Longlat":"String content", "Name":"String content" }] } |
||
notifications/ { USERID }
|
GET |
Get the notification list |
-NA- |
[{ "deviceId":2147483647, "deviceName":"String content", "notificationId":2147483647, "reason":"String content", "sensorId":2147483647 }] |
||
notifications/ delete/ {NOTIFICATIONID } |
GET |
Deletes a notification |
-NA- |
Success |
||
Sensor |
sensor
Content Type: application/json |
POST |
Adds a sensor for given deviceid. |
{ "Deviceid":2147483647, "Fault_tolerance":2147483647, "Id":2147483647, "Interval_measure":"String content", "Interval_send":"String content", "Make":"String content", "Metadata":"String content", "Name":"String content", "Status":true, "Type":"String content" } |
Success |
|
sensor/ { SENSORID }
|
GET |
Gets the specified sensor |
-NA- |
{ "href":"http:\\www.example.com\Services\sensor\{sensorid}", "Sensorid":{ "Deviceid":2147483647, "Fault_tolerance":2147483647, "Id":2147483647, "Interval_measure":"String content", "Interval_send":"String content", "Make":"String content", "Metadata":"String content", "Name":"String content", "Status":true, "Type":"String content" }} |
||
Sensors ?deviceid={DEVICEID}
|
GET |
Gets a list of all sensors for associated with a given DEVICEID |
-NA- |
[{ "href":"http:\\www.example.com\Services\sensor\{sensorid}", "Sensorid":{ "Deviceid":2147483647, "Fault_tolerance":2147483647, "Id":2147483647, "Interval_measure":"String content", "Interval_send":"String content", "Make":"String content", "Metadata":"String content", "Name":"String content", "Status":true, "Type":"String content" }}] |
||
sensor/ {SENSORID}/ trigger
|
GET |
Gets the trigger for a given sensor |
-NA- |
{ "LowerLimit":1.26743233E+15, "Name":"String content", "UpperLimit":1.26743233E+15, "sensorId":2147483647 } |
||
sensor/ { SENSORID }/ trigger Content Type: application/json |
POST |
Sets the trigger for a given sensor |
{ "LowerLimit":1.26743233E+15, "Name":"String content", "UpperLimit":1.26743233E+15 } |
Success |
||