IDS Data API

The data access APIs provide simple programmable and flexible approach to accessing the events data stored in IDS and is an alternative to using the individual API types. It also query the meta data about the stored events. This metadata can be used further to automate the usage of the data access API.

This APIs allow querying current, history and bulk events data stored in IDS. The user can query the data by specifying the eventName and filters. For more information on querying the data, see Events API.

Note: The Current and History APIs can be used in Grafana. The bulk APIs are for streaming large amounts of data to files.

The filters work efficiently when they are picked from the available list of keys and should be ordered as they appear in the keys. When the filters provided are not efficient or filters are not part of the keys then the API fails with 400 error. In such cases a header execute-inefficient-queries can be set to true which results in running queries which are inefficient.

Note: The queries with execute-inefficient-queries header add load on the DB and might impact its performance. These queries should not be used.

Current APIs

URI Method Description 
/ids-data-api/v2/current/{event}?<filter1>=<filter1>&<filter2>=filter2
GET This API retrieves the most recent data of the specified event. The data can be filtered by specifying filter based on the keys supported by the event.

Example

Request: 
: http://localhost:36153/ids-data-api/v2/current/observation_event?serialnumber=tenant1serial222
Response: 

[
  {
    "serialnumber": "tenant1serial2222",
    "resourcepath": "/device/0/battery",
    "customattributes": {},
    "groupname": "ddpi.ed.tenant1",
    "servertime": "2023-04-03 07:38:22.297Z",
    "subscriptionid": "idserial2222",
    "value": "34"
  },
  {
    "serialnumber": "tenant1serial2222",
    "resourcepath": "/device/1/temp",
    "customattributes": null,
    "groupname": "ddpi.ed.tenant1",
    "servertime": "2023-02-12 07:38:23.297Z",
    "subscriptionid": null,
    "value": "40C"
  }
]

Sample Requests:

http://localhost:36153/ids-data-api/v2/current/observation_event?serialnumber=ddpi.ed.tenant1serial111
http://localhost:36153/ids-data-api/v2/current/observation_event?serialnumber=ddpi.ed.tenant1serial2222&resourcepath=/device/0/battery
http://localhost:36153/ids-data-api/v2/current/observation_event?serialnumber=ddpi.ed.tenant1serial2222&resourcepath=/device/0/battery,/device/1/temp

Historical APIs

URI Method Description 
/ids-data-api/v2/history/{event}?fromTime=<fromTime>&toTime=<toTime>&
filter1=<filter1>&filter2=filter2
 GET

This API retrieves the most historical data of the specified event.

The fromTime and toTime filters are mandatory.

The data can be further filtered by specifying filter based on the keys supported by the event.

Example

Request: 
http://localhost:45279/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T17:09:41&toTime=2023-04-03T17:09:41&resourcepath=/device/0/battery,/device/1/temp&serialNumber=tenant1serial2222

Response:


      [
  {
    "pid": "20230212",
    "serialnumber": "tenant1serial2222",
    "resourcepath": "/device/1/temp",
    "servertime": "2023-02-12 11:39:41.096Z",
    "customattributes": null,
    "groupname": "ddpi.ed.tenant1",
    "subscriptionid": null,
    "value": "40C"
  },
  {
    "pid": "20230403",
    "serialnumber": "tenant1serial2222",
    "resourcepath": "/device/0/battery",
    "servertime": "2023-04-03 11:39:40.096Z",
    "customattributes": null,
    "groupname": "ddpi.ed.tenant1",
    "subscriptionid": "idserial2222",
    "value": "34"
  }
]

Sample Requests:

http://localhost:45279/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T17:09:41&toTime=2023-04-03T17:09:41
http://localhost:36235/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T18:47:22&toTime=2023-04-03T18:47:22.000Z&serialNumber=tenant1serial111
http://localhost:36235/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T18:48:08.829Z&toTime=2023-04-03T18:48:08&serialNumber=ddpi.ed.tenant1serial111,ddpi.ed.tenant1serial2222 
http://localhost:36235/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T18:46:30.881Z&toTime=2023-04-03T18:46:30&resourcepath=/device/0/battery&serialNumber=tenant1serial111
http://localhost:45279/ids-data-api/v2/history/observation_event?fromTime=2023-02-12T17:09:41.096Z&toTime=2023-04-03T17:09:41.000Z&resourcepath=/device/0/battery,/device/1/temp&serialNumber=ddpi.ed.tenant1serial2222

Secondary Filter

Using secondary filtering, the data retrieved from the database can be further filtered by specifying the filtering expression in the API query call. The secondary filtering feature can be used with any of the supported events.

For more information, see Events API section to get the details on supported events and their key ordering.

Syntax:

The secondary filtering is supported using the following parameter sequence. The filter is expressed with function-like syntax which takes parameters as input.

<function-name>(<column-name>, <value>, <data-type>) [AND <function-name>(<column-name>, <value>, <data-type>) ]

Where:

Parameter Description
function-name The comparator function which will be run against the stored value with the input value.
column-name The column whose value will be compared against the input value. Example, resourcePath.
value The input value against which the stored value will be compared.
data-type The data type of the input value. If required, the input value will be converted to this data type. If the conversion fails, then the call will be rejected.
Note: When multiple conditions are there, then they can be combined using a logical AND operator. Currently, only AND operation is supported.

Following are the supported data types:

  • int - integer
  • double - Double
  • boolean - Boolean
  • str - String

Functions

Function Description Example
contains This function checks whether the value of the column contains the supplied string. contains(resourcePath, 1, str)
endsWith This function checks whether the value of the column ends with the supplied string. endsWith(resourcePath, /temp, str)
equals This function checks whether the value of the column is equal to the value supplied. equals(value, 42, int)
greaterThan This function checks whether the value of the column is greater than the value supplied. greaterThan(value, 34, int)
greaterThanOrEqual This function checks whether the value of the column is greater than or equal to the value supplied. greaterThanOrEqual(value, 34, int)
lessThan This function checks whether the value of the column is less than the value supplied. lessThan(value, 65, int)
lessThanOrEqual This function checks whether the value of the column is less than or equal to the value supplied. lessThanOrEqual(value, 42, int)
notEquals This function checks whether the value of the column is not equal to the value supplied. notEquals(value, 10.0, double)
startsWith This function checks whether the value of the column starts with the supplied string. startsWith(resourcePath, /device, str)

Sample expressions

  • equals(resourcePath, /device/0/battery, str)
  • equals(resourcePath, /device/1/temp, str) AND equals(value, 42, int)
  • equals(resourcePath, /device/0/battery, str) AND greaterThan(value, 34, int) AND lessThan(value, 65, int)

Bulk APIs

URI Method Description 
/ids-data-api/v2/bulk/{event}??fromTime=<fromTime>&toTime=<toTime>
 GET

This API streams all the historical data of the specified event. between the specified date range.

The fromTime and toTime filters are mandatory.

Note: The API ignores the time part of the date for efficiency and returns all the events between the specified date.

Example

Request:
http://localhost:45709/ids-data-api/v2/bulk/observation_event?fromTime=2023-02-12T18:38:41&toTime=2023-04-03T18:38:41
Response:
[
  {
    "pid": "20230212",
    "serialnumber": "ddpi.ed.tenant1serial2222",
    "resourcepath": "/device/1/temp",
    "servertime": "2023-02-12 13:08:41.188Z",
    "customattributes": null,
    "groupname": "ddpi.ed.tenant1",
    "subscriptionid": null,
    "value": "40C"
  },
  {
    "pid": "20230403",
    "serialnumber": "ddpi.ed.tenant1serial111",
    "resourcepath": "/device/0/battery",
    "servertime": "2023-04-03 13:08:40.188Z",
    "customattributes": {
      "attribute": "ddpi.ed"
    },
    "groupname": "ddpi.ed.tenant1",
    "subscriptionid": "",
    "value": "65"
  },
  {
    "pid": "20230403",
    "serialnumber": "ddpi.ed.tenant1serial2222",
    "resourcepath": "/device/0/battery",
    "servertime": "2023-04-03 13:08:40.188Z",
    "customattributes": null,
    "groupname": "ddpi.ed.tenant1",
    "subscriptionid": "idserial2222",
    "value": "34"
  }
]