Web Service API

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.

Device Registration:

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.    

  • Interval Measure (sec): Represents the time interval between each data recording.
  • Interval Send (sec): Represents periodic time interval for sending data to the web service.
  • Make: Represents the hardware manufacturer name.
  • Type: Represents the type of the sensor. Eg. GPS, temperature/humidity and Barometer.
  • Fault Tolerance (sec): Represents the maximum time period for fault. If a device does not send any data more than this time period, the sensor will be flagged as ‘offline’.

Data Logging:

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.

Data Retrieval:

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.

Complete list of API

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

             

Last edited Sep 12, 2013 at 11:38 AM by comarios, version 1