IOStash v0.1 API documentation

Platform Overview

IOStash platform has the following data hierarchy.

Data Overview

Reading and writing data is the core of IOStash, managing & distributing that data is the primary application of IOStash API.

IOStash API makes it easy for your devices, applications and services to read and write data to IOStash and through IOStash to each other. IOStash supports reading and writing data via three resources: Channels, Devices and Datapoints.

Channel: The channel is at the top of the IOStash Data hierarchy. A channel is simply a collection of devices, that you'd like to group together. For example, suppose you're building a network of weather stations across your city, you will want to group all the stations (devices) that contribute to your data. This grouping of devices can help you obtain collective data and also, you can address all of them by the channel name. If you are a product manufacturer, you might want to use channels for a particular line of products.Channels are like groups, you can send messages to every single device in the channel via the messaging API. A channel has its own meta data associated with it. These meta data includes the channel name, a unique id, the devices associated with it and the details about its creation and ownership. Channel specific queries that enable data selection, filtering and comparison are available via the API.

   channel:{
    	channelName,
    	devices:[Array of memeber devices]
    }

Device: A device (also called a producer) is an entity that sends data to the IOStash platform. A device can be a microcontroller, a mobile phone or even an application that sends data to the platform. A device is identified by its DeviceID parameter, which is unique across the IOStash platform. You'll have to use your device ID to read/write data from/to the particular device.
A device can be of two types, Static or Dynamic. A Static device is the one that is geographically static, which means that the device is stationary at a particular point. For example, a weather station. A Dynamic device is the one which is not stationary at a particualar point. For example, a vehicle tracker or a Quadcopter. All devices will have its own meta data including device name, its id, description, location data (for a static device, installation location is used), the data points associated with it and the channels it is a part of. A collection of devices form a channel and a device can be a part of multiple channels.

 device: { 
        deviceName,
        type: [static/dynamic],
        description,
        isPublic: [true/false],
        enabled:[true/false],
        geoLocation: {
            latitude,
            longitude
        },
        dataPoints:[array of data points associated],
        channels:[array of channels, the device is a member of],
        dateCreated,
        dateActivated,
        lastValue,
        deviceControl:[{
            control,
            creationDate,
            status:[true/false]
         }]
        }

Data Point: A Datapoint represents a single value of a metric (a physical value read by a device) at a specific point in time. It is simply a key value pair consisting of a timestamp and the value at that time. A device can have multiple data points. They are the bare data units in the IOStash platform. A data point is identified by its name. A device can have multiple unique data points. Data points can store any type of value, including integer, float, double, boolean or string. IOStash platform does not impose any kind of type restrictions on the datapoints.

dataPoint:[{
    	value,
    	commitTime
    	}]
       

RESTful API Overview

IOStash RESTful API provides RESTful methods to read/write data. For most low power, low performance microcontrollers (Arduino, for example), RESTful APIs are the way to go when connecting them to the internet. You can use these APIs with your microcontrollers or your applications.

IOStash RESTful API provide language neutral data access to your devices and your applications. Since these APIs are platform/language independant, you can use these for any type of application involving IOStash data access, while ensuring security and flexibility.

To get a list of available end points, perform a /GET on

https://api.iostash.io/0.1/details/

Responses

IOStash will return responses for all queries and commands including when data is written. All responses will be having the HTTP header 200.

Success Response

{
error: false,
message: <message_goes_here>
}

          

Error Response

{
error: true,
message: <error_message_goes_here>
}

          

Realtime API Overview

IOStash realtime API provides javascript methods for receiving realtime data updates from your devices and/or channels. Purpose of these APIs is to give the developer an option to listen for data changes in realtime and perform actions accordingly without explicitly reading for data changes.

Realtime API is available as nodejs module and javascript library for use in web applications. To install IOStash npm module, execute:

$ npm install iostash 

IOStash web client library is available via the JSDelivr CDN. Add it to your apps by including :

<script type="text/javascript" src="https://cdn.jsdelivr.net/iostash/0.1/iostash.js"></script>

IOStash realtime API uses Socket.io over SSL for sockets communication. It should be noted that only secure connections are supported at the moment.

Initialization

Before listening to any events, initialization function has to invoked with the user's x-access-token. init() function is responsible for the connection establishment with IOStash servers. There are two initialization methods available, init(x-access-token) and initPublic(deviceID).

init() method is to be used in applications where the source code of the application is not available to the public, like in server side applications. initPublic() function is to be used in applications where the source code of the application is available to the public and the device is set as public. It is to be used when storing x-access-token in plain text accessible to the public is a security concern. Note that while using initPublic(), deviceID of the public device is to be passed instead of the x-access-token.

If initPublic() is used, only a public device and its data points can be listened to, channels and private devices cannot be accessed.

Responses

All data update callbacks will return data as a JSON response with the following strucutre:

{
eventDescription, //Available in all updates
deviceId, //In case of a channel update
update: {
      dataPointName : updated_value, //Available in all updates
      commitTime, //Available in all updates
      msgId //Unique ID of the message
      }
}

eventDescription can be one of either dataPointUpdate, deviceUpdate, channelUpdate or customDataPublished. deviceId will hold the id of the device that caused the update in case of a channelUpdate event. dataPointName will have the name of the datapoint that changed and its corresponding value.

Listening to Data Point Updates

To subscribe to a dataPoint update from a single device, the following has to be used in case of a private device/server side code. The callback will be executed everytime a new data is pushed to the specified data point.

iostash.init('x-access-token');
iostash.subscribeDataPoint('DEVICE_ID','DATAPOINT_NAME',function(data){

//perform actions based on 'data'

});
          

eventDescription field will hold 'dataPointUpdated' in this case. If the user doesn't have permission to access the device or the datapoint doesn't exist or an invalid device id is specified, the library will show an alert using window.alert() in case of web application library or display the error using console.log() in case of a nodejs application.

If the device is a public device, initPublic('DEVICE_ID') is to be used instead of init('x-access-token').

To unsubscribe from the datapoint in a later point of time, the following is to be used

iostash.unsubscribeDataPoint('DEVICE_ID','DATAPOINT_NAME',function(data){

//'data' holds success message

});
          

Listening to Device Updates

To subscribe to a device for updates, the following is to be used. Whenever the specified device pushes data, the associated callback will be executed. init() and initPublic() functions can be used for initialization.

iostash.init('x-access-token');
iostash.subscribeDevice('DEVICE_ID',function(data){

//perform actions based on 'data'

});

eventDescription field will hold 'deviceUpdate' in this case. Listening to a device will result in receiving updates from all of the data points in the device. It is like listening to all of the data points defined in the device. If the user doesn't have permission to access the channel or an invalid channel id is specified, the library will show an alert using window.alert() in case of web application library or display the error using console.log() in case of a nodejs application.

If the device is a public device, initPublic('DEVICE_ID') is to be used.

To unsubscribe from the datapoint in a later point of time, the following is to be used

iostash.unsubscribeDevice('DEVICE_ID',function(data){

//'data' holds success message

});
          

NOTE: On successful subscription, the callback will receive the last update pushed by the device by default.

Listening to Channel Updates

To subscribe to a channel for updates, the following is to be used. Whenever a device in the specified channel pushes data, the associated callback will be executed. Only init() function can be used for initialization.

iostash.init('x-access-token');
iostash.subscribeChannel('CHANNEL_ID',function(data){

//perform actions based on 'data'

});

eventDescription field will hold 'channelUpdate' in this case. Listening to a channel will result in receiving updates from all of the devices in the specified channel. It is like listening to all of the devices defined in the channel. If the user doesn't have permission to access the channel or an invalid channel id is specified, the library will show an alert using window.alert() in case of web application library or display the error using console.log() in case of a nodejs application.

To unsubscribe from the channel in a later point of time, the following is to be used

iostash.unsubscribeChannel('DEVICE_ID','DATAPOINT_NAME',function(data){

//'data' holds success message

});
          

Listening to Location Updates

Location data of a geographically dynamic device can be listened to with the Realtime API. Whenever the device updates its location, the corresponding callback will be executed. This callback will only be executed if both latitude and longitude datapoints are pushed. Update will hold the newly pushed latitude and logitude pair along with the commitTime.

iostash.init('x-access-token');
iostash.subscribeLocation('DEVICE_ID',function(data){

//perform actions based on 'data'

});

eventDescription field will hold 'locationUpdate' in this case. If an invalid deviceID is specified, system will return error. In case of a geographically static device, this function is of no use as no location updates will be available.

Listening to Custom Data

Custom data sent to a particualr device can be listened to using this API. Custom events can be sent via the RESTful API or the MQTT interface. The callback associated with this API will be executed when a custom data is published. This is useful in keeping track of the actions performed by the device upon receiving a custom data or for analytical applications.

iostash.init('x-access-token');
iostash.subscribeCustomData('DEVICE_ID',function(data){

//perform actions based on location 'data'

});

eventDescription field will hold 'customDataPublished' in this case. Data is sent as JSON key value pairs and will be received as is. Rest of the update object remains like in other events.

MQTT Realtime API

IOStash supports MQTT interface for data communication, which can be used for pushing data or for listening to data updates from devices or channels. This API is aimed to be used in devices with connectivity and processing constraints. IOStash supports QoS 1 for all system topics and updates, and hence a unique client ID is required while connecting via MQTT. Like in other interfaces, MQTT API also uses JSON for data exchange.

NOTE: IOStash cannot be used as a general purpose MQTT broker, only predefined topics which are discussed below are supported.

For using MQTT, the following host URL and port is to be used

Host URL: api.iostash.io
Port: 1883

Authentication

IOStash MQTT API requires authentication for publishing and subscribing topics. Pass x-access-token as the username and the device secret which is created during device creation as the password. Set client id to the deviceID. If listening to data updates, set a unique name as client ID or else messages will be delivered with QoS 0 instead of QoS 1.

Topics

Like every other MQTT broker, topics are at the core of IOStash MQTT API. However, unlike general purpose MQTT brokers, IOStash does not support generic user defined topics or $SYS topics. Also ,unlike generic brokers, IOStash will not disconnect on data/protocol/subscribe errors. Instead, error message will be published to the topic x-access-token/deviceID/system or x-access-token/system, depending on the error context.
NOTE: Leading slash in topics is mandatory.

Writing Data

Data can be published to IOStash from devices by publishing to the corresponding device's topic. Data must be a valid JSON object/string and the user must have access to the device.
To publish data, the following topic is to be used with corresponding x-access-token and deviceID.

/x-access-token/deviceID

For IOStash to recognize and persist data, it must be in the following JSON format:

{
"datapoint": value,
"datapoint": value
}

Once the data is persisted, response will be published to

/x-access-token/deviceID/system

{
error: false,
message: "Data Saved",
messageId: UNIQUE_MESSAGE_ID,
commitTime: TIME_OF_COMMIT 
}

Subscribing to Device Updates

For device updates, the following topic can be subscribed to with correspoding x-access-token and deviceID. If the user does not have access to the device, error will be published to /system topic.

/x-access-token/deviceID

New updates will be received as JSON strings of following format:

{
eventDescription, 
update: {
      dataPointName : updated_value,
      commitTime,
      msgId
      }
}

Subscribing to Channel Updates

For channel updates, the following topic can be subscribed to with correspoding x-access-token and channelID. If the user does not have access to the channel, error will be published to /system topic

/x-access-token/channelID

New updates will be received as JSON strings of following format:

{
eventDescription,\
deviceId,
update: {
      dataPointName : updated_value,
      commitTime,
      msgId
      }
}

Subscribing to Custom Data Updates

For custom data updates sent to device, the following topic can be subscribed to with correspoding x-access-token and deviceID. If the user does not have access to the device, error will be published to /system topic

/x-access-token/deviceID/custom

Subscribing to Trigger Actions

Trigger action data sent by a trigger can be listened to, by subscribing to the following topic with the correspoding x-access-token and deviceID. If the user does not have access to the device, error will be published to /system topic

/x-access-token/deviceID/actions