Data is sent to the API via the /Stream endpoint. Here, data is queued to be processed, and then stored. There are three types of valid message that may be sent to the API. The following examples will hopefully show how these message must be composed.
Currently the XML format is not supported when POSTing to the Stream. Please use JSON instead.
Datum POST
Single datum posts are, as you'd expect, comprised of just a single DateTime and Value pair.
The Type field is set to 1 - which indicates that this post purely contains data to be processed and stored.
The DataPointIdID for the DataPoint must be included for this.
<!-- POST -->
https://nexcloud.io/v1.0/Stream
<!-- HEADER -->
Accept : application/json
Content-Type : application/json
<!-- BODY -->
{
"Type" : 1, // Type 1 means reading data.
"Message" :
{
"DataPointID" : 68367854, // "Room Temperature" UI1 DataPoint.
"Value" : 22.7, // This is the reading value (numerical).
"DateTime" : "2016-03-16T16:20:23.456Z" // UTC time when value was read (ISO 6801).
}
}
Data POST
The Multiple Data Post is nearly identical in form, except that the DateTime and Value are moved to an array.
<!-- POST -->
https://nexcloud.io/v1.0/Stream
<!-- HEADER -->
Accept : application/json
Content-Type : application/json
<!-- BODY -->
{
"Type" : 1, // Type 1 means reading data.
"Message" :
{
"DataPointID" : 68367854, // "Room Temperature" UI1 DataPoint.
"Data" : [
{
"Value" : 22.7,
"DateTime" : "2016-03-16T16:20:23.456Z"
},
{
"Value" : 22.8,
"DateTime" : "2016-03-16T16:22:16.673Z"
},
{
"Value" : 22.6,
"DateTime" : "2016-03-16T16:24:43.998Z"
},
...
]
}
}
Error POST
The final type of message that can be sent to the Stream is an Error post. If there is a problem with a Device or DataPoint, for example it is no longer reachable on the LAN, you should send an error message to the Cloud. This way users will be notified and see the fault condition.
The Type being set to 2 immediately marks this message as being specific to an error. At a minimum, the ControllerID must be provided. If possible, you can then provide the DeviceID. Then, if the error can be traced right to an individual DataPoint, you may include this as well. The code number is assigned a message - you can check the list of codes here. If one doesn't match an error you are faced with, contact us and we will add codes you require. Finally, the DateTime should be provided, however the Value field is entirely optional and may in fact not make sense to include.
<!-- POST -->
https://nexcloud.io/v1.0/Stream
<!-- HEADER -->
Accept : application/json
Content-Type : application/json
<!-- BODY -->
{
"Type" : 2,
"Message" :
{
"ControllerID": 123,
"DeviceID": 456,
"DataPointID": 789,
"Code": 4601,
"DateTime": "2016-06-01T04:03:08Z",
"Value" : "27.3"
}
}