Data Web API

The data web api can be used to retreive data from an running open.WARE instance. The answer will be in JSON Format as described in Basic Data Format. All requests must contain a Authorization header with an JWT-Bearer-Token or OD-SESSION header which contains a valid session for the running instance.

Items

The items API can be used to retrieve all items / sensors / data sources an user has access to. The repsonse will be an JSON array containing entries as described in Basic Data Format

The API is available via:

{{host}}/api/data/items/

You will receive an complete list of all data items available to the user including their current value. To limit the results to a specific source, just add the respective source tag as a route parameter:

{{host}}/api/data/items/source

The result will be filtered list only containig data items that belong to the source

Live

The live API can be used to retrieve live values of a given data item at a given time. The API is available via:

{{host}}/api/data/live/{{source]]/{{ID}}

Parameter	Description
SOURCE	The source tag of the data source the data item belongs to
ID	The data item's id within the source

Past Live Values

Sometimes it is desireable to access live data of certain point in time in the past. For this use case the API provides options to define the point in time and the amount of values to retrieve via query parameters

{{host}}/api/data/live/{{source]]/{{ID}}?at={{TIMESTAMP}}&values={{AMOUNT}}

Parameter	Description
TIMESTAMP	The timestamp in milliseconds for which lives values will be retrieved. Meaning that the system will return one or more values that were collected before or at the desired time(timestamp of value <= TIMESTAMP)
AMOUNT	Number of values to retreive, e.g. a value of 3 would return the last three value before TIMESTAMP

The repsonse will be an JSON object containing as described in Basic Data Format

Historical

The historical API can be used to retrieve historical batches of data. The API is available via:

{{host}}/api/data/historical/{{source}}/{{id}}/{{start}}/{{end}}

Parameter	Description
source	The source tag of the data source the data item belongs to
id	The data item's id within the source
start	An timestamp indicating the earliest point in time of which data should be retrieved
end	An timestamp indicating the latest point in time of which data should be retrieved

The repsonse will be an JSON object containing as described in Basic Data Format

Resolution of the data

Sometimes it is desireable to limit the amount of data. For this use case the API provides options to define a resolution of the data. It can be used to limit the amount of data while keeping the characteristics of the timeseries. You can use the feature by providing query parameters as follows:

{{host}}/api/data/historical/{{source}}/{{id}}/{{start}}/{{end}}?mode={{MODE}}&maxValues={{AMOUNT}}

Parameter	Description
source	The source tag of the data source the data item belongs to
id	The data item's id within the source
start	An timestamp indicating the earliest point in time of which data should be retrieved
end	An timestamp indicating the latest point in time of which data should be retrieved
mode	The way of how the data should be sampled. Currenty only minmax is available.
amount	The max amount of values that should be returned. The service does not guarantee the exact amount but only that their will be less values in the reponse

Filter data

Sometimes it is desireable to only retreive data where certain values are present or within a certain range. For this use case the API provides options to define a filter of the data. It can be used to filter the data based on freely definable filtes. You can use the feature by providing a query parameter as follows:

{{host}}/api/data/historical/{{source}}/{{id}}/{{start}}/{{end}}?filter={{filterString}}

Parameter	Description
source	The source tag of the data source the data item belongs to
id	The data item's id within the source
start	An timestamp indicating the earliest point in time of which data should be retrieved
end	An timestamp indicating the latest point in time of which data should be retrieved
filterString	The String that will be parsed as an SpEL and result in an boolean value

An example filter expression that will only retrieve values where the first dimension of the sensor is greater than 5 and the second dimension is a string with value "foo" looks like

val[0].value()>5 and val[1].value().equals('foo')

Pay attention to the .value() when accessing the actual value. If errors occur during expression evaluation the respective value will be filtered

Push or Update Data

Use the following endpoints to POST data to the system:

Adding data:

{{host}}/api/data/push

Updating data:

{{host}}/api/data/update

The body in each case must be an JSON-Object following the Basic Data Format. Based on the provided credentials (Header containing JWT oder OD-SESSION) it will be checked, if the user has access to writing this data.