DateTime Specification

Flume uses ISO8601 DateTime specification for all datetimes excluding when querying for water usage. Datetimes are in UTC and use the T delimiter with the Z suffix except for querying water usage. The format when querying for water usage is a modification of the ISO8601 specification that replaces T delimiter with a space and the Z is omitted as the timezone of the datetime is either the respective to the device or defined by the user making the call.

Date

ISO8601 specifies a variety of formats for the <date> element but Flume restricts the <date> element to YYYY-MM-DD yielding valid examples such as 2016-01-15 but not 20160116. The month and day parts of a <date> element must be zero padded so 2016-01-09 is valid while 2016-1-9 is not.

Time

ISO8601 specifies a variety of formats for the <time> element but Flume restricts the <time> element to HH:II:SS yielding valid examples of 14:22:21 but not 142221. As for the <date> element, all parts of a <time> element must be zero padded so 04:02:01 is valid while 4:2:1 is not.

Timezones and Formats

The APIs is responsible for resolving from UTC to an appropriate local time if necessary on a read.

Querying water usage simply uses local time. For example when querying water usage data with the provide range of 2017-01-01 00:00:00 - 2017-02-01 00:00:00 the backend will add the proper offsets to get the correct range in UTC using the timezone set for that device. So the query on the backend may look like 2016-12-31 14:00:00 - 2016-01-30 14:00:00 if the devices timezone has a -10:00 offset. The backend will then output the time as expected in local time with the original range.

Ranges

While any Date and Time specification should allow for historical dates there seems no need for Flume to represent Dates and Times prior to 2000-01-01 00:00:00 thus it is recommended to restrict historical ranges to not before 2000-01-01 00:00:00 as a sanity or validation check.