Historical Datastore REST API exposes the following top-level endpoints:
/registry- basic CRUD of data sources, simple search/filter API similar to that of the Resource Catalog, and (optionally) configuration of data aggregation.
/data- populating the datastore with new data (publishing new sensor measurements), retrieving last values of a single and multiple data sources, as well as querying historical data by time and other attributes
/aggr- optional querying the configured aggregated data by time and other attributes
The Historical Datastore can also be implemented in read-only mode (e.g., when providing a façade for legacy systems). In this case, the Registry API and Data API are read-only and Aggregation API is implementation specific.
The OpenAPI (Swagger) specification can be explored here.
The representation formats provided in the API responses use a custom MIME type, which is set in the headers of all responses and carries the API version:
Describes the registry of registered data sources
urlis the URL of the Registry (
entriesis an array of Data Source objects
totalare used for paging
Describes a single data source such as a sensor (LinkSmart Resource)
idis a unique id of the data source (set by the server)
urlis the URL of the Data Source in the registry (
datais the URL to the Data API (
resourceis the URL identifying the resource. This should match the SenML name of measurements for this data source.
metais a hash-map with optional meta-information
retentiondefines the retention policy, which is the period of time that the data will be kept (at least that long). It is specified as a decimal number with units, such as "1h", "1w", etc. Valid time units are "m" (minutes), "h" (hours), "d" (days), and "w" (weeks).
aggregationis an array of configured aggregations in the format of Aggregated Data Source. It is optional and there can be 0..* aggregations defined for a Data Source.
typeis the value type used in payload. The following basic types are supported:
formatis the MIME type of the payload used by the Data Source, e.g.,
Aggregated Data Source
Describes a data aggregation for a Data Source. Aggregation is optional and supported only for Data Sources using the
idis the aggregation id, a unique identifier representing each set of interval and aggregates
intervalis the aggregation interval, specified in the period format used in
datais the URL to the Aggregate API (
aggregatesis an array of aggregates calculated on each interval. Valid values are
retentionis the retention policy in the same format as in Data Source
Describes the recordset returned on querying the Data API
urlis the URL of the returned recordset in the Data API
datais a SenML root element with data entries, where Name (
n) constitute the
resourceURL of the corresponding Data Source(s)
timeis the time of query in milliseconds
totalare are used for paging of the Recordset
Describes the recordset returned on querying the Aggregate API
totalare the same as for Data Recordset
datais a document with data records in the SenML-like Aggregate Data Set format
Aggregate Data Set
Describes a set of aggregated data records in the format similar to SenML root element
buhave the same meaning and semantic as in SenML (Base Name and Base Unit)
bteare the Base Time Start and Base Time End indicating the timestamp of the beginning and end of the aggregation time interval correspondingly
eis an array of aggregated data entries in the Aggregate Data Entry format
Aggregate Data Entry
Describes an aggregated data entry similar to the SenML entry (element of
e array) describing a single measurement with 'float' value
nhas the same meaning and semantic as in SenML, overriding the corresponding attributes of the Aggregate Data Set. Note that Name (
n) must constitute the
resourceURL of the Data Source(s) whose data is aggregated.
te, if provided, override the
medianare the aggregates (those that are not configured are omitted)