Best practices

Best practices for getting current objects and data

When you intend to retrieve a large number of objects in an environment through Connect API, such as Agents, we always recommend using version of the API endpoint for getting all available objects in an environment in one go, instead of fetching each asset object individually.

Doing so will both reduce the time to retrieve all asset objects - and avoids doing looping in your code for retrieval - as well as place less load on the API. These endpoints are:

• Get full list of all Agents for environment
• Get full list of all Applications for environment
• Get full list of all Products for environment
• Get full list of all Product Groups for environment
• Get full list of all user logons

If only small subset of all asset objects will be needed, then separate calls to retrieving each Agent, Product etc. individually is sensible course of action.

📘

Suggested frequency

As Applixure processes each environment's data (devices, software etc.) only periodically into information available through the Web UI or Connect API, it does not make sense to poll the list of asset objects from the API too frequently as they are guaranteed to be not changed from the previous run. As Applixure's object graph is stateless in nature, Applixure Connect API does not have a concept for retrieving only the changed (or new) data since the previous run.

Presently, the minimum interval for getting all asset object should be set to two hours. As the Agents also have interval by which they send the data to the Applixure backend, suggsted minimum time for re-retrieving asset objects or associated data is four hours.

📘

Suggested backoff time

If the Connect API returns error condition that is a transient condition (i.e. not "object not found" type situation), caller should maintain reasonable backoff or wait time before retrying the operation. Suggested backoff time is 10 seconds, with increasing backoff time if the endpoint continue to report transient error condition.

Best practices for getting historical objects and data

Historial asset objects, such as for Agents and Product Groups, are created by the Applixure backend from the current day's data at the UTC timezone date rollover.

These historical asset objects generally won't be changed anymore after the fact unless Agent device sends buffered data from multiple preceding days (for example due to being out-of-communication from the Internet for several days), which may augment things like device and software issue events for those days, which weren't originally present in the Agent or Product Group data for particular historical dates. In this case, the historical asset object entries may be updated with the newly received data to make them up-to-date representing information from those past dates.

For this reason it is strongly recommended that callers of Connect API do not retrieve historical data for asset objects too frequently, and that historical information is cached on the caller site.
Unlike the current data that's getting updated as Agents send the data during the same day, historical object entries are most likely not changed from the previous retrieval.

Furthermore, retrieving historical data creates larger pressure against the Applixure backend and the API as the platform is optimized for use of the current information, which means that retrieval time for historical information can be higher and the amount of data returned [as JSON] is significantly larger, even with compression at the HTTP level.

Like with the current data and object, versions of the API endpoints for retrieving historical data for all assets in the environment is strongly recommended against fetching each Agent, Product Group etc. history entry individually in loop.

Special consideration should however be made in larger environments (1000+ Agents) for retrieving only limited amount of history depth in one API call as the amount of information can be significant in size. We recommend fetching at maximum of one week's worth of historical data in one call when using the mass retrieval endpoints, such as when getting getting history information for all Agents by using a date-range parameter:

https://connect.applixure.com/v1/environmentId/agents/history/20201001-20201008

(please note that you will need to calculate appropriate dates for the parameters, in the preceding example range is from October 1st 2020 to October 8th 2020)

📘

Suggested frequency

The minimum interval for getting all historical entries should be set to 24 hours.