Delta Support for device/devices API
Last updated on 07 October, 2024We’ve observed that throughout a day customers query LogicMonitor APIs multiple times to get the latest updates on their devices, its properties, and more. This involves human efforts, consumes several hours, and is prone to errors. For example, LogicMonitor monitors your 5 thousand devices. You make an API call /device/devices to fetch these devices and store them in your local database. Usually, devices undergo several changes such as name change, updates to device properties, and more. To ensure that the data monitored by LogicMonitor is latest and reliable, you query LogicMonitor APIs multiple times, store the data, and run automation over it to identify the delta (latest changes) to create an informative dashboard. In this process you rapidly consume the rate limit. For example, even if only 10 devices have been updated, you eventually consume data worth 5 thousand devices. This also impacts performance of LogicMonitor.
To bridge this gap and help you quickly get the delta, we have added two new endpoints to /device/devices API. They are:
- GET
/santaba/rest/device/devices/delta– Registers delta request and generates a new delta Id. It also returns all devices that match the filter criteria. - GET
/santaba/rest/device/devices/delta/<DELTAID>– Returns devices that have any delta between the last and the current API call.
Note: Currently, we have added the delta feature only to /device/devices API endpoints.
Any user with read permission for devices can make these two GET calls to get delta for devices.
Generating Delta ID
The delta ID is generated using the API request GET /santaba/rest/device/devices/delta. The delta ID is then subsequently used in API request GET /santaba/rest/device/devices/delta/<DELTAID> to get the modified devices data.
Note:
- The delta ID expires in 30 minutes from the time of its generation. If the delta ID is used within 30 minutes to get the modified device data, then its expiry window increases by 30 minutes from the time of its use.
- You can see delta on only those parameters which are performed on the LogicMonitor UI. Therefore, properties updated via active discovery (AD) are not part of delta.
You can add basic or nested filters to the GET call to get the response that includes the updated devices and specified filters.
URI: GET /santaba/rest/device/devices/delta
| Parameter | Type | Description |
size | Integer | Indicates the number of result to display. A maximum of 1000 result can be requested in a GET call.Example – /santaba/rest/device/devices/delta?size=1000 |
offset | Integer | Indicates the number of result to offset the displayed result. Example – /santaba/rest/device/devices/delta?offset=1000 |
filter | String | The response is filtered to include only the specified filter criteria. Note that the delta response contains only those devices that match the filter criteria.For basic filters, see REST API Basic Filters Example – /santaba/rest/device/devices/delta?filter=name~"127.0.0.1" |
deltaId | Integer | The deltaId is used in pagination. In the first GET call, the field remains empty and the response returns the deltaId.From the second pagination request onwards, provide the same deltaId that was returned in the first API call.Example – /santaba/rest/device/devices/delta?deltaId=e3c7cb05f23e477eb06ea1a1cc5d6c96 |
Pagination
For pagination, provide size, offset, filter, and deltaId to return all results for the same deltaId.
First page request:
/santaba/rest/device/devices/delta?offset=0&size=1000&filter=name~"127.0.0.1"This request returns all devices that match the filter and the deltaId.
From the second page request onwards, provide the deltaIdfor all page requests. To retrieve all devices that match the filter, call the same API multiple times with the same deltaId (generated in the first call) with offset=0.
/santaba/rest/device/devices/delta?offset=1000&size=1000&filter=name~"127.0.0.1"&deltaId=XXXXXXXXXXRequest and Response
The response is similar to that of GET device/devices API. See Devices Fields.
Observe that the deltaId is displayed towards the end of the response.
Note: The response does not include details of deleted devices.
Request Example
API - /santaba/rest/device/devices/delta?filter=name~"127.0.0.1"&size=10&offset=0Response Example
Response
{
"total": 1,
"searchId": null,
"items": [
{
"id": 1,
"name": "127.0.0.1",
"displayName": "127.0.0.1_collector_1",
"deviceType": 0,
"relatedDeviceId": -1,
"currentCollectorId": 1,
"preferredCollectorId": 1,
"autoBalancedCollectorGroupId": 0,
"preferredCollectorGroupId": 1,
"preferredCollectorGroupName": "@default",
"description": "",
"createdOn": 1678369453,
"updatedOn": 1678450158,
"disableAlerting": false,
"autoPropsAssignedOn": 0,
"autoPropsUpdatedOn": 0,
"scanConfigId": 0,
"link": "",
"enableNetflow": false,
"netflowCollectorId": 0,
"netflowCollectorGroupId": 0,
"netflowCollectorGroupName": null,
"isPreferredLogCollectorConfigured": false,
"currentLogCollectorId": 0,
"logCollectorId": 0,
"logCollectorDescription": null,
"logCollectorGroupId": 0,
"logCollectorGroupName": null,
"lastDataTime": 0,
"lastRawdataTime": 0,
"hostGroupIds": "17,16,13,4",
"sdtStatus": "none-none-none",
"userPermission": "write",
"rolePrivileges": [],
"hostStatus": "dead-collector",
"alertStatus": "unconfirmed-critical-none",
"alertStatusPriority": 1,
"awsState": 1,
"azureState": 1,
"gcpState": 1,
"alertDisableStatus": "none-none-none",
"alertingDisabledOn": null,
"collectorDescription": "8a9c17559226",
"netflowCollectorDescription": null,
"customProperties": [
{
"name": "test",
"value": "55"
},
{
"name": "snmp.community",
"value": "********"
},
{
"name": "system.categories",
"value": "snmpHR,linux,collector"
}
],
"resourceIds": null,
"upTimeInSeconds": 0,
"deletedTimeInMs": 0,
"toDeleteTimeInMs": 0,
"hasDisabledSubResource": false,
"ancestorHasDisabledLogicModule": false,
"systemProperties": [
{
"name": "system.enablenetflow",
"value": "false"
},
{
"name": "system.collectorplatform",
"value": "linux"
},
{
"name": "system.collectorid",
"value": "1"
},
{
"name": "system.deviceId",
"value": "1"
},
{
"name": "system.prefcollectordesc",
"value": "8a9c17559226"
},
{
"name": "system.collectordesc",
"value": "8a9c17559226"
},
{
"name": "system.groups",
"value": "DeltaTestDeviceGroup,Minimal Monitoring,Devices by Type/Collectors,Devices by Type/Linux Servers"
},
{
"name": "system.deviceGroupId",
"value": "17,16,13,4"
},
{
"name": "system.collector",
"value": "true"
},
{
"name": "system.ips",
"value": "127.0.0.1"
},
{
"name": "system.resourceCreatedOn",
"value": "1678369453"
},
{
"name": "system.devicetype",
"value": "0"
},
{
"name": "system.collectorversion",
"value": "33002"
},
{
"name": "system.prefcollectorid",
"value": "1"
},
{
"name": "system.displayname",
"value": "127.0.0.1_collector_1"
},
{
"name": "system.hoststatus",
"value": "dead-collector"
},
{
"name": "system.hostname",
"value": "127.0.0.1"
}
],
"autoProperties": [],
"inheritedProperties": [
{
"name": "PropUpdate",
"value": "updated-2023/3/27-03:34:11"
},
{
"name": "netapp.ssl",
"value": "true"
}
],
"syntheticsCollectorIds": []
"status": ""
}
],
"deltaId": "XXXXXXXXXX"
}Note: By default, the status field remains empty because the GET request only generates the deltaId and fetches devices that match the filter.
Getting Delta
URI: GET /santaba/rest/device/devices/delta/<DELTAID>
This API call returns only those devices that have delta between the last and the current API call.
It returns only those devices that match the filter criteria specified at the time of generating the deltaId.
| Parameter | Type | Description |
offset | Integer | Indicates the number of result to offset the displayed result. Example – /santaba/rest/device/devices/delta/XXXXXXXXXX?offset=1000 |
size | Integer | Indicates the number of result to display. A maximum of 1000 result can be requested in a GET call. Example – /santaba/rest/device/devices/delta/XXXXXXXXXX?size=1000 |
Pagination
For pagination, provide size and offset values. If the offset is 0 then it returns the next delta. Subsequently, for every page, increase the offset value by page size. For example, 1000, 2000, 3000, and so on.
Example
/santaba/rest/device/devices/delta/XXXXXXXXXX?offset=0&size=1000and
/santaba/rest/device/devices/delta/XXXXXXXXXX?offset=1000&size=1000Request and Response
In the response, only the updated information of devices is displayed, such as updates to device property or any operation performed on the LogicMonitor UI. The response is similar to GET /device/devices. See Devices Fields. The new field deltaId is added towards the end.
The status field indicates if the data is added, updated, or deleted.
- For added or updated device – the response displays all fields with the latest values.
- For deleted device – the response displays only the
id,name, anddisplayNameand status asdeleted. All the remaining fields display the default values.
Request Example
/santaba/rest/device/devices/delta/XXXXXXXXXX?size=10&offset=0Response Example
Sample response for an updated device.
{
"total": 1,
"searchId": null,
"items": [
{
"id": 1,
"name": "127.0.0.1",
"displayName": "127.0.0.1_collector_1",
"deviceType": 0,
"relatedDeviceId": -1,
"currentCollectorId": 1,
"preferredCollectorId": 1,
"autoBalancedCollectorGroupId": 0,
"preferredCollectorGroupId": 1,
"preferredCollectorGroupName": "@default",
"description": "Updated Description...",
"createdOn": 1678369453,
"updatedOn": 1678450158,
"disableAlerting": false,
"autoPropsAssignedOn": 0,
"autoPropsUpdatedOn": 0,
"scanConfigId": 0,
"link": "",
"enableNetflow": false,
"netflowCollectorId": 0,
"netflowCollectorGroupId": 0,
"netflowCollectorGroupName": null,
"isPreferredLogCollectorConfigured": false,
"currentLogCollectorId": 0,
"logCollectorId": 0,
"logCollectorDescription": null,
"logCollectorGroupId": 0,
"logCollectorGroupName": null,
"lastDataTime": 0,
"lastRawdataTime": 0,
"hostGroupIds": "17,16,13,4",
"sdtStatus": "none-none-none",
"userPermission": "write",
"rolePrivileges": [],
"hostStatus": "dead-collector",
"alertStatus": "unconfirmed-critical-none",
"alertStatusPriority": 1,
"awsState": 1,
"azureState": 1,
"gcpState": 1,
"alertDisableStatus": "none-none-none",
"alertingDisabledOn": null,
"collectorDescription": "8a9c17559226",
"netflowCollectorDescription": null,
"customProperties": [
{
"name": "test",
"value": "55"
},
{
"name": "snmp.community",
"value": "********"
},
{
"name": "system.categories",
"value": "snmpHR,linux,collector"
}
],
"resourceIds": null,
"upTimeInSeconds": 0,
"deletedTimeInMs": 0,
"toDeleteTimeInMs": 0,
"hasDisabledSubResource": false,
"ancestorHasDisabledLogicModule": false,
"systemProperties": [
{
"name": "system.enablenetflow",
"value": "false"
},
{
"name": "system.collectorplatform",
"value": "linux"
},
{
"name": "system.description",
"value": "Updated Description..."
},
{
"name": "system.collectorid",
"value": "1"
},
{
"name": "system.deviceId",
"value": "1"
},
{
"name": "system.prefcollectordesc",
"value": "8a9c17559226"
},
{
"name": "system.collectordesc",
"value": "8a9c17559226"
},
{
"name": "system.groups",
"value": "DeltaTestDeviceGroup,Minimal Monitoring,Devices by Type/Collectors,Devices by Type/Linux Servers"
},
{
"name": "system.deviceGroupId",
"value": "17,16,13,4"
},
{
"name": "system.collector",
"value": "true"
},
{
"name": "system.ips",
"value": "127.0.0.1"
},
{
"name": "system.resourceCreatedOn",
"value": "1678369453"
},
{
"name": "system.devicetype",
"value": "0"
},
{
"name": "system.collectorversion",
"value": "33002"
},
{
"name": "system.prefcollectorid",
"value": "1"
},
{
"name": "system.displayname",
"value": "127.0.0.1_collector_1"
},
{
"name": "system.hoststatus",
"value": "dead-collector"
},
{
"name": "system.hostname",
"value": "127.0.0.1"
}
],
"autoProperties": [],
"inheritedProperties": [
{
"name": "PropUpdate",
"value": "updated-2023/3/27-03:34:11"
},
{
"name": "netapp.ssl",
"value": "true"
}
],
"syntheticsCollectorIds": [],
"status": "updated"
}
],
"deltaId": "XXXXXXXXXX"
}Sample response for a deleted device.
{
"total": 1,
"searchId": null,
"items": [
{
"id": 17,
"name": "1.1.1.1",
"displayName": "1.1.1.1",
"deviceType": 0,
"relatedDeviceId": -1,
"currentCollectorId": 0,
"preferredCollectorId": 0,
"autoBalancedCollectorGroupId": 0,
"preferredCollectorGroupId": 0,
"preferredCollectorGroupName": null,
"description": null,
"createdOn": 0,
"updatedOn": 0,
"disableAlerting": false,
"autoPropsAssignedOn": 0,
"autoPropsUpdatedOn": 0,
"scanConfigId": 0,
"link": null,
"enableNetflow": false,
"netflowCollectorId": 0,
"netflowCollectorGroupId": 0,
"netflowCollectorGroupName": null,
"isPreferredLogCollectorConfigured": false,
"currentLogCollectorId": 0,
"logCollectorId": 0,
"logCollectorDescription": null,
"logCollectorGroupId": 0,
"logCollectorGroupName": null,
"lastDataTime": 0,
"lastRawdataTime": 0,
"hostGroupIds": null,
"sdtStatus": "none-none-none",
"userPermission": null,
"rolePrivileges": null,
"hostStatus": "normal",
"alertStatus": "none",
"alertStatusPriority": 100000,
"awsState": 1,
"azureState": 1,
"gcpState": 1,
"alertDisableStatus": "none-none-none",
"alertingDisabledOn": null,
"collectorDescription": null,
"netflowCollectorDescription": null,
"customProperties": null,
"resourceIds": null,
"op": null,
"upTimeInSeconds": 0,
"deletedTimeInMs": 0,
"toDeleteTimeInMs": 0,
"hasDisabledSubResource": false,
"ancestorHasDisabledLogicModule": false,
"systemProperties": null,
"autoProperties": null,
"inheritedProperties": null,
"syntheticsCollectorIds": null,
"status": "deleted"
}],
"deltaId": "XXXXXXXXXX"
}