Jamf Pro API Scalability Best Practices

Overview

This article describes the best practices related to performance and scalability with Jamf Pro APIs and how to effectively build an application that is resilient and performant.

📘

Notice

These best practices serve as a guideline for interacting with Jamf Pro APIs. Not all environments are hosted or resourced in the same manner, so your mileage may vary.

Rate Limiting

Jamf Pro does not have a built-in solution to restrict or limit the number of API requests made over a given time interval. However, there are some guidelines that we recommend to provide an appropriate balance between quickly performing the tasks your application requires of the API and not inundating the system with requests, such that it fails to perform other basic functions.

1. Limit your interactions with Jamf APIs to no more than 5 concurrent connections.
   1. By using no more than 5 concurrent connections, you can ensure that other Jamf Pro tasks are still able to occur without impacting Jamf Pro administrators or managed client devices.
   2. Some API initiated workflows can spawn many additional processes or calculations that need to be performed by the server, and these often are not reflected in the response time of your API call. For example, changes to a smart group could impact any number of deployable objects, triggering installation or removal on hundreds or thousands of devices. In extreme scenarios, consuming server resources for exclusively API related activities could prevent managed devices from processing the request, in a timely manner.
2. Measure response times and dynamically adjust time between requests accordingly.
   1. Interactions with API endpoints may have a large variance in response time based on a variety of factors:
      1. Type of resource you’re interacting with.
      2. The size of the organization (e.g. number of managed devices).
      3. The organization’s specific server settings and configuration (e.g. server resources, log flushing settings, etc.).
3. By measuring response times, your application can establish a baseline or “normal”, allowing for adjustments to be made when outside of “normal”.

Error Handling

Even the best designed applications will encounter errors. Building logic into your application that intelligently handles errors will provide resilience and a better user experience. Generally speaking, Jamf recommends the use of an exponential backoff algorithm. This will improve performance for both the server and client by reducing server load and reducing the number of error responses received by the client. This type of algorithm is often closely coupled with rate limiting, since it effectively determines the rate at which your application sends requests to the API.

Please review the API Overview documentation for each API as well as the API Reference materials. Common error codes and recommendations on how clients should handle those are described within these resources.

Syncing Device Inventory Data

One of the most commonly used operations with Jamf APIs is to fetch data about managed devices. Many applications ingest this information and often have a recurring sync process which fetches new data on a set interval or frequency. Before setting any guidelines or recommendations, let's get an understanding of how Jamf Pro receives new data from managed device.

Mobile Devices (iOS, tvOS, iPadOS)

Jamf Pro has a global setting to configure how frequently mobile devices submit new inventory records. By default, this is configured to 1 day (24 hours). This setting cannot be configured to be more frequent than daily, but it can be extended to weekly or monthly.

In addition to the recurring sync process for all inventory data, certain tasks when initiated by Jamf Pro, will prompt for a subset of new device data to be submitted. For example, when a configuration profile is installed on a device, Jamf Pro will request a list of all installed profiles to validate that the process completed successfully. This same type of behavior occurs when apps are installed by Jamf Pro, as well as various other deliverables. These partial updates to inventory do not change the value of the “Last Inventory Update” on the device record, however they will trigger the MobileDeviceCheckIn webhook event.

Finally, one-off requests can be made via the UI and API for devices to submit a full set of device data. Requests made in this manner will update the “Last Inventory Update” value, as well as reset the timer on when the next automated recurring update occurs.

Computers (macOS)

Jamf Pro has a slightly different method of collecting inventory data on macOS devices, which provides more configurability than mobile devices. Instead of a single global setting, inventory for macOS devices is enabled via the use of a policy. Most environments have a policy dedicated solely to updating inventory data, often on a daily (24 hour) basis to align with the mobile device platform.

Unlike mobile devices, Jamf Pro does not support partial update for computers. Since no partial update exists, it’s very common for administrators to include the “Update Inventory” option within a policy which performs tasks such as application updating or installation, simply to validate that the policy successfully completed the task it was designed for.

All policies with the “Update Inventory” check box enabled will request new data from a device and update the value of the “Last Inventory Update” field on the device record. Unlike mobile devices, for computers, this does not reset the time on when the next automated recurring inventory update occurs. All policies track their own execution frequency independent of other policies.

Frequency of Syncs

Now that we have a better understanding of how often new inventory data is available to Jamf Pro, we can begin to explore methods for exporting that data to external systems in an efficient manner. Generally speaking, Jamf Pro does not collect new inventory data more than once per day per device.

If your application would like to request data more frequently than every 24 hours, Jamf Pro recommends the use of Webhooks. This allows Jamf Pro to notify your application in realtime when a device has submitted new inventory data to Jamf Pro. In most cases, the response body for inventory related events will not include all the information about a device that your application needs, therefore a subsequent API call may be necessary to fetch the complete data set. This can be done at the time the event is received, or queued as part of a batch.

For applications that do not require realtime data, Jamf recommends performing full inventory syncs no more than once every 24 hours. To further optimize performance and remove redundant data, Jamf recommends using a filter to request only devices that have submitted inventory within the last day. This can be accomplished via the Jamf Pro API for computers, via the use of the general.reportDate filter parameter. For mobile devices no similar filter currently exists, however sorting via the lastInventoryUpdateDate sort parameter can be used similarly when combined with small page sizes. By using these filters, you can obtain a list of only the devices which have submitted inventory since the specified date. For more information on filtering, see Filtering with RSQL.