Dynamic IDS Data API

The data access APIs provides 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

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"
  }
]

Events API

This API returns the type of events stored in the system. The response contains the details like name, the key and the columns with their types for available for each of the events. This API can be used to query the data stored under each of those event types. The eventName field can be used to query the current, history and bulk data using this APIs. The keys information can be used to further filter the data while using the data access APIs.


URI	Method	Description
`/ids-data-api/v2/events/`	GET	Get the event types stored in the system.

Sample

{
 "eventName": "aggregation_event",
 "keys": ["pid", "groupname", "ruleid", "metric", "servertime"],
 "fields": {
   "winstarttime" : "TIMESTAMP",
   "winendtime" : "TIMESTAMP",
   "metric" : "TEXT",
   "servertime" : "TIMESTAMP",
 }
 
}