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](BasicDataFormat.md). 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](BasicDataFormat.md) 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](BasicDataFormat.md) ## 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](BasicDataFormat.md) ### 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](https://docs.spring.io/spring-framework/docs/3.2.x/spring-framework-reference/html/expressions.html) and result in an boolean value. The expression can make use of existing Java methods of the data values (e.g. `String.startsWith` or `String.contains`. Further you can make use of logical operators `and`, `or `& `!`. See the SpEL Documention for more information | 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](BasicDataFormat.md). Based on the provided credentials (Header containing JWT oder OD-SESSION) it will be checked, if the user has access to writing this data.