Sensor Data Upload API Documentation

Introduction

The Sensor Data Upload API provides a restful web service to access to the RPI Sensor Data Service database. Users could utilize these APIs in their own applications to manage their sensor data via the web services.

Data Objects

The data objects used in Sensor Data Service RPI are listed as follows:

• User : A person who signed up on our portal and maybe also register sensors in the system.
• Sensor : A device at a particular geolocation, which can operate to collect measured data.
• Datastream : A stream of observations of a phenomena produced by measuring components such probes.
• Record : A measured value of a certain phenomena at a specific point of time

The relationship of data objects used in Sensor Data Service RPI is listed as follows:

• A User could register multiple Sensors
• A Sensor has one or more Datastreams
• A Datastream could produce measured Records over time

Data Object: User

• id : the email of the user
• uid : the unique identifier of the user, generated by the system
• firstName : the first name of the user
• lastName : the last name of the user

Data Object: Sensor

• id : the id of the sensor
• uid : the unique identifier of the sensor, generated by the system
• user : the id of the user who owns this sensor
• altitude : the altitude of the sensor
• height : the height of the sensor
• samplingrate : the sampling rate of the sensor
• title : the title of the sensor
• nickName : the nick name of the sensor
• description : the description of the sensor
• last_time_online : the last time when the sensor communicated with the system
• phens : a list of phenomena observed by the datastreams on the sensor
• tag: tag string provided by users

Data Object: Datastream

• id : the id of the datastream
• uid : the unique identifier of the datastream, generated by the system
• sensor : the id of the sensor which this datastream belongs to
• user : the id of the user who owns the corresponding sensor
• phenName : The name of the phenomena which this datastream is observing
• unit : The unit of measurement of the pheomena which this datastream is observing
• tag: tag string provided by users

Data Object: Record

• id : the time in utc when the measurement occurs
• uid : the unique identifier of the record, generated by the system
• reading : the value of the measurement
• tag: tag string provided by users
• comment: comment string provided by users
• dateTime : the time in the user’s local time zone when the measurement occurs

api_key

• api_key must be sent with all client requests. The api_key helps the server to validate the request source. Please email [email protected] to get an API key.

Account Management

Scenario: Retrieve a list of users

• When I send a GET request for http://ip:port/users/
• Then the response should be 200
• And the response should have an array of users

Scenario: Retrieve details of a user

• When I send a GET request for http://ip:port/users/{user_id}
• Then the response should be 200
• And the response should have a user

Scenario: Create a user

• When I send a POST request for http://ip:port/users/
• With a json string containing details of a user
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Update a user

• When I send a PUT request for http://ip:port/users/{user_id}
• With a json string containing updated information of a user
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Remove a user

• When I send a DELETE request for http://ip:port/users/{user_id}
• Then the response should be 200
• And the response should include a status indicating success or failure

Sensor Management

Scenario: Retrieve a list of sensors owned by a user

• When I send a GET request for http://ip:port/users/{user_id}/sensors
• Then the response should be 200
• And the response should have an array of sensors

Scenario: Retrieve details of a sensor

• When I send a GET request for http://ip:port/users/{user_id}/sensors/{sensor_id}
• Then the response should be 200
• And the response should have a sensor

Scenario: Create a sensor

• When I send a POST request for http://ip:port/users/{user_id}/sensors/
• With a json string containing details of a sensor
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Update a sensor

• When I send a PUT request for http://ip:port/users/{user_id}/sensors/{sensor_id}
• With a json string containing updated information of a sensor
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Remove a sensor

• When I send a DELETE request for http://ip:port/users/{user_id}/sensors/{sensor_id}
• Then the response should be 200
• And the response should include a status indicating success or failure

Datastream Management

Scenario: Retrieve a list of datastreams from a sensor

• When I send a GET request for http://ip:port/users/{user_id}/sensors/{sensor_id}/datastreams/
• Then the response should be 200
• And the response should have an array of datastreams

Scenario: Retrieve details of a datastream

• When I send a GET request for http://ip:port/users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}
• Then the response should be 200
• And the response should have a datastream

Scenario: Create a datastream

• When I send a POST request for http://ip:port/users/{user_id}/sensors/{sensor_id}/datastreams/
• With a json string containing details of a datastream
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Update a datastream

• When I send a PUT request for http://ip:port/users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}
• With a json string containing updated information of a datastream
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Remove a datastream

• When I send a DELETE request for http://ip:port/users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}
• Then the response should be 200
• And the response should include a status indicating success or failure

Observation Management

Scenario: Retrieve a list of records observed by a datastream

• When I send a GET request for http://ip:port/ users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}/records
• Then the response should be 200
• And the response should have an array of records

Scenario: Retrieve details of a record

• When I send a GET request for http://ip:port/ users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}/records/{record_id}
• Then the response should be 200
• And the response should have a record

Scenario: Create a record

• When I send a POST request for http://ip:port/ users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}/records/
• With a json string containing details of a record
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Update a record

• When I send a PUT request for http://ip:port/ users/{user_id}/sensors/{sensor_id}/datastreams/{datastream_id}/records/{record_id}
• With a json string containing updated information of a record
• Then the response should be 200
• And the response should include a status indicating success or failure

Scenario: Remove a record

• When I send a DELETE request for http://ip:port/users/{user_id}/sensors/{sensor_id}datastreams/{datastream_id}/records/{record_id}
• Then the response should be 200
• And the response should include a status indicating success or failure

Appendix

Conventions

• Client - Client application.
• Status - HTTP status code of response.
• All the possible responses are listed under ‘Responses’ for each method. Only one of them is issued per request server.
• All responses are in JSON format.
• All request parameters are mandatory unless explicitly marked as [optional]
• Status Codes

All status codes are standard HTTP status codes. The below ones are used in this API.

• 2XX - Success of some kind
• 3XX - Redirection
• 4XX - Error occurred in client’s part
• 5XX - Error occurred in server’s part

#Service Level Agreement ##Request Limits

• We current limit each application issuing maximum 360 request per hour.