Page tree
Skip to end of metadata
Go to start of metadata

REST API

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.


Representation Formats

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:

application/vnd.eu.linksmart.hds+json;version=0.0.1


Registry

Describes the registry of registered data sources

{
    "url": "string",
    "entries": [],
    "page": "int",
    "per_page": "int",
    "total": "int"
}

where:

  • url is the URL of the Registry (/registry)
  • entries is an array of Data Source objects
  • pageper_pagetotal are used for paging


Data Source

Describes a single data source such as a sensor (LinkSmart Resource)

{
    "id": "<uuid>",
    "url": "string",
    "data": "/data/<uuid>",
    "resource": "string",
    "meta": {},
    "retention": "string",
    "aggregation": [],
    "type": "string",
    "format": "string"
}
where:
  • id is a unique id of the data source (set by the server)
  • url is the URL of the Data Source in the registry (/registry/id)
  • data is the URL to the Data API (/data/id)
  • resource is the URL identifying the resource. This should match the SenML name of measurements for this data source. 
  • meta is a hash-map with optional meta-information
  • retention defines 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).
  • aggregation is 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.
  • type is the value type used in payload. The following basic types are supported: stringboolfloat.
  • format is the MIME type of the payload used by the Data Source, e.g., application/senml+json)


Aggregated Data Source

Describes a data aggregation for a Data Source. Aggregation is optional and supported only for Data Sources using the float value type.

{
    "id": "string",
    "interval": "string",
    "data": "/aggr/<interval>/<uuid>",
    "aggregates": [],
    "retention": "string"
}
where:
  • id is the aggregation id, a unique identifier representing each set of interval and aggregates
  • interval is the aggregation interval, specified in the period format used in retention
  • data is the URL to the Aggregate API (/aggr/id)
  • aggregates is an array of aggregates calculated on each interval. Valid values are meanstddevsumminmaxmedian.
  • retention is the retention policy in the same format as in Data Source


Data Recordset

Describes the recordset returned on querying the Data API

{
    "url": "string",
    "data": {},
    "time": "int",
    "page": "int",
    "per_page": "int",
    "total": "int"
}
where:
  • url is the URL of the returned recordset in the Data API
  • data is a SenML root element with data entries, where Name (bn and n) constitute the resource URL of the corresponding Data Source(s)
  • time is the time of query in milliseconds
  • pageper_page, and total are are used for paging of the Recordset


Agregate Recordset

Describes the recordset returned on querying the Aggregate API

{
    "url": "string",
    "data": {},
    "time": "int",
    "page": "int",
    "per_page": "int",
    "total": "int"  
}
where:
  • urltimepageper_page, and total are the same as for Data Recordset
  • data is 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

{
    "bn": "string",
    "bu": "string",
    "bts": "int",
    "bte": "int",
    "e": []
}
where:
  • bn and bu have the same meaning and semantic as in SenML (Base Name and Base Unit)
  • bts and bte are the Base Time Start and Base Time End indicating the timestamp of the beginning and end of the aggregation time interval correspondingly
  • e is 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 v.

{
    "n": "string",
    "ts": "int",
    "te": "int",
    "mean": "float",
    "stddev": "float",
    "sum": "float",
    "min": "float",
    "max": "float",
    "median": "float"
}
where:
  • n has the same meaning and semantic as in SenML, overriding the corresponding attributes of the Aggregate Data Set. Note that Name (bn and n) must constitute the resource URL of the Data Source(s) whose data is aggregated.
  • ts and te, if provided, override the bts and bte attributes correspondingly
  • meanstdsumminmax, and median are the aggregates (those that are not configured are omitted)
  • No labels