Live Objects - complete developer guide

Store service

The REST interface allows to add data to a stream and to retrieve data from a stream. A stream could be for example associated to a unique of device (streamID could be therefore a device Identifier) or one type of data coming from a device (streamID could be therefore in this format deviceIdentifier-typeOfData)

Manage your data streams

Every source publishing or injecting the data into Live Objects (Device, gateway or business application), must set the stream which would be where you want to store your data.

In order to be able to use and process the data collected correctly, it is necessary to be able to read it and then store it. The management of the read and write processes in Live Objects is done through data stream channels.

A data stream is associated with each publisher and it can be a device with a single interface or several, you must take into consideration where the published messages will be written.

By default, each provisioned device, Live Objects associates a streamId with the defaulDataStreamId whose value is set automatically by Live Objects. The messages will be written under this stream.

So, to correctly manage the streams of your device, you should either use the stream provided by default or modify it if necessary.

When you want the device to use a particular streamId, the publisher must indicate in each uplink the desired stream. This allows data to be writed and stored as needed.

Figure 1. Data stream options

Default data stream payload :

{

    "value": {"temp":23.8},
    "model": "data_model_v1"
}

Your data are stored under the defaultDataStreamId value stream. In this case the value is a device URN (or the value that you set in defaultDataStreamId field).

Custom data stream payload :

{
    "streamId" : "my_stream_1"
    "value": {"temp":24.1},
    "model": "data_model_v1"
}

To change your Custom data stream :

{
    "streamId" : "my_stream_2"
    "value": {"temp":20.1},
    "model": "data_model_v1"
}

In the device side, make sure to set the device’s custom streamId properly (set correctely the payload published by the device), as it determines which stream the message will be published to. Otherwise, messages will be sent to the configured/defaultStreamId (configure it in Live objects UI)

Add a data message to a stream

Request:

POST /api/v0/data/streams/{streamId}
X-API-Key: <your API key>
Accept: application/json

body param

description

data

JSON object conforming to data message structure

Warning: the streamId is provided as the last segment of the url.

Example:

POST /api/v0/data/streams/myDeviceTemperature

{
  "value": {"temp":24.1},
  "model": "data_model_v0"
 }

For this example, the "value.temp" field of model "data_model_v0" will be defined as a double type. If a String type is used in the future for "value.temp", a new model must be defined. In case that "value.temp" is set a String type with model "data_model_v0", the message will be dropped by the search service.

Add an encoded data message to a stream

In order to use the decoding capability of Live Objects, a DataMessage must contains additional 'value.payload' and 'metadata.encoding' fields :

Example:

POST /api/v0/data/streams/myDeviceTemperatureAndPressure

{
    "value": {
        "payload": "000003F5000000DD"
    },
    "metadata": {
        "encoding": "twointegers"
    }
}

Field	Description
*value.payload*	(Mandatory). Payload to decode. In case of binary content, HexBinary String representation of the payload to decode.
*metadata.encoding*	(Mandatory). Encoded format name, that should match the 'encoding' name of the decoder that can process this message.

Field

Description

value.payload

(Mandatory). Payload to decode. In case of binary content, HexBinary String representation of the payload to decode.

metadata.encoding

(Mandatory). Encoded format name, that should match the 'encoding' name of the decoder that can process this message.

All other fields of DataMessage (timestamp, model, location, tags…) can also be set in the encoded DataMessage.

You can also set the encoding property in the device’s interface definition in order to force metadata.encoding value for all data messages sent from this device through its interface.

Add a bulk of data messages

Request:

POST "/api/v0/data/bulk
X-API-Key: <your API key>
Accept: application/json

body param

description

data

JSON array conforming to an array of data message structure

A bulk will be processed if all arrays elements are valid, otherwise the bulk will be rejected. Maximum size of the bulk is 1000.

Warning : the streamId is mandatory for each element of the Bulk. This is a difference with the REST API for adding data to a stream.

Example:

POST /api/v0/data/bulk

[
  {
    "streamId" : "temperature_stream_1"
    "value": {"temp":24.1},
    "model": "data_model_v1"
  },
  {
    "streamId" : "temperature_stream_1"
    "value": {"temp":24.1},
    "model": "data_model_v1"
  },
  {
    "streamId" : "pressure_stream_1"
    "value": {"pressure":1024.0},
    "model": "data_model_v1"
  }
]

Retrieve data from a stream

Request:

GET /api/v0/data/streams/{streamId}
X-API-Key: <your API key>
Accept: application/json

Query params

Description

limit

Optional. max number of data to return, value is limited to 100

timeRange

Optional. filter data where timestamp is in timeRange "from,to"

bookmarkId

Optional. id of document. This id will be used as an offset to access to the data.

Documents are provided in reverse chronological order (newest to oldest).

Example:

GET /api/v0/data/streams/myDeviceTemperature

{
  "id": "57307f6c0cf294ec63848873",
  "streamId": "myDeviceTemperature",
  "timestamp": "2016-05-09T12:15:41.620Z",
  "model": "temperature_v0",
  "value": {
    "temp": 24.1
  },
  "created": "2016-05-09T12:15:40.286Z"
}