APIs and Apple Device Management: A Guide for Mac Admins (Part 2)

A while back, we offered up an introductory tutorial on APIs and how they’re used in the context of managing Apple devices. Apple admins use APIs all the time, whether they know it or not. Knowing the basics of how those APIs work and how they can be manipulated is essential knowledge for any Apple admin. 

We wanted to follow up on that overview with a look at a few other API essentials, including tools you can use to work with APIs, the differences between public and private APIs, and how to manage the data returned by API calls.

But first a quick refresher: There are many types of APIs. However, the most common when it comes to device management is a representational state transfer (REST) API. A REST API allows software, services, and scripts to reach out and communicate over HTTP protocols. For a REST API, there are five types of requests a client can send to a server:

• GET: Obtain information 
• POST: Add or update information 
• PUT: Replace information 
• PATCH: Update certain information 
• DELETE: Remove information

API Tools and Scripting

Interacting with an API usually happens in one of two ways: with a GUI tool such as an app or through a script.

GUI tools are particularly great for prototyping and testing an API; at a minimum, they let you make requests and see the responses. Their major advantage is that, generally, they are easier than writing scripts. Postman is one of the most popular GUI tools, but it is not the only one by any means. Other options include Testsigma, RapidAPI (formerly PAW), Insomnia, and Testfully. 

One thing to consider when choosing a GUI tool to interact with your own API is whether it has specific documentation for your environment. For example, Postman has documentation specifically for Kandji. There is also documentation from Kandji for working with Postman. 

Scripts are the other way to interact with an API. We included a few examples of such scripts in our previous post. As another example, consider this script, which will prompt the user for a device_id and then lock the device—all without needing to navigate into the Kandji web app.

#!/bin/bash 

deviceID=$(osascript << EOF 

tell application "System Events" to text returned of (display dialog "What is the Device ID of the device you want to lock?" default answer "" buttons {"OK"} default button 1) 

EOF) 

curl --location --request POST 'https://{SubDomain}.clients.us-1.kandji.io/api/v1/devices/'$deviceID'/action/lock' --header 'Authorization: Bearer {apiToken}' 

(Note: In the code examples above and below, a string in italics and single brackets—such as {SubDomain} or {apiToken}—indicates a placeholder variable that you'd need to replace as appropriate for your own use case.)

Scripts can also be automated via launch daemons to perform repetitive or maintenance tasks. As an example, a launch daemon can run a script to restart the computer once per week.

The cons of using scripts for interacting with the API are the same cons that always come with scripts: They are more difficult to construct and they require you to climb a steeper learning curve. There is also no room for error in scripting: If not written correctly, the script will fail, or even worse, do something unintended; there is no undo with a script. So, be sure to test thoroughly before using a script in production scenarios.

Public vs. Private APIs 

As a Mac admin, you’ll usually deal with two types of APIs: public and private. (There’s a third, less common type: the partner API.) Regardless of which type of API you’re dealing with, the basic functionality is the same: The API allows one service to talk to another via a common language understood by both services. 

A public API is exactly what it sounds like: It's an API that is open and viewable to anyone and can be used without restrictions. Two of the more popular public APIs that Apple admins interact with: 

• Github is the standard repository for software development. Its API lets you automate the development process, by managing your organization’s repository and branches.
• IPSW.me is where you can download current and previous versions of macOS, iOS, and iPadOS installers. (It also has watchOS, tvOS, and audioOS.) The site has documentation for interacting with its API. You can, for example, use an API call to get all available firmware for a specific device, such as iPhone14,2, or to download a specific iOS version based on the device and build ID. 

Unlike public APIs, private APIs aren’t available to everyone. They require some form of authentication—typically a token—before you can access them. With that authentication provided, your API requests are made via HTTPS and the data exchange will be encrypted. 

To access the Kandji API, you can create multiple tokens. Each has a corresponding unique API key, which provides the necessary level of access. For information on creating API tokens and configuring access, see the documentation here. 

As we explained before, you can leverage the Kandji API to do things like getting a list of all enrolled devices: 

Or you can get information about a specific device, by adding a parameter to your API call to specify a serial number: 

You can also use a GET request to the Kandji API to retrieve a FileVault recovery key: 

curl --location --request GET 'https://{SubDomain}.clients.us-1.kandji.io/api/v1/devices/{deviceID}/secrets/filevaultkey/' --header 'Authorization: Bearer {apiToken}' 

You can use a POST request to add or update information, such as setting a computer name or enabling/disabling Remote Desktop.

curl --location -g --request POST 'https://{SubDomain}.clients.us-1.kandji.io/api/v1/devices/{deviceID}/action/setname/' --header 'Content-Type: application/json' --header 'Authorization: Bearer {apiToken}' --data-raw '{ "DeviceName": "Test Mac Mini" }' 

curl --location --request POST 'https://{SubDomain}.clients.us-1.kandji.io/api/v1/devices/{deviceID}/action/remotedesktop' --header 'Content-Type: application/json' --header 'Authorization: Bearer {apiToken}' --data-raw '{ "EnableRemoteDesktop": true }' 

The Kandji API not only lets you interact with your Kandji instance; it also enables other businesses and providers to work with Kandji. Okta Workflows are one example. In Okta’s words, “Kandji’s API allows Okta Workflows to call actions in Kandji. Kandji can then make changes to the device in response to events or changes with Okta Cloud Identity.” So, for example, if a user is promoted or moved to a different department in Okta, Okta can tell Kandji to make make the necessary changes to their computer. 

Managing API Results: Pagination, Arrays, Dictionaries, and Loops

Once you've sent an API request, you need to deal with the results that are returned. Depending on the type of request you are making, such as a GET, you may get hundreds or thousands of results. This can quickly become unwieldy, putting a strain on your system or the API resources being accessed.

Pagination can be used to break up larger responses into smaller, more manageable chunks or pages. That's less resource-intensive, because you won’t be pulling as much data from the API service with each request. If you've ever performed a search request in Google, you’ve seen paginated content in action.

There are several ways to implement pagination, depending on how the API was designed. For example, some APIs use the concept of pages. These attributes are generally returned in an API response and contain links to the previous, current, and next pages of results, allowing the user to navigate through the list of results in the API. Other APIs implement pagination using a flavor of limit and offset parameters. These let the user define how many results to return in each response (limit) and which record to start with when making the next request (offset). 

For example, the Kandji API has a List Devicesendpoint that returns a list of devices in a given Kandji tenant. An API call to that endpoint in a deployment of 15,000 devices could result in a reply with 15,000 responses on a single page. But that endpoint has a default upper limit set to return 300 results per request. You can go lower by editing the limit= parameter in the request URL for your GET calls. There are several examples of pagination to can be found on Kandji’s Github. This script, for example, combines limit and offset until all device records are returned.

Arrays are another way of compiling data and are suitable for storing and accessing data in a list format. A simple array using Bash or Zsh can look like this:

myArray=("cat" "rat" "dog")

Once created, you can access a single array element like this:

echo "${myArray[1]}"

Or show all elements using a loop:

for item in "${myArray[@]}"; do
    echo "${item}"
done

Another common data structure returned from an API is a dictionary. A good example of an array is the way data is returned when calling the devices endpoint in the Kandji API. Data is returned in a way that is readable by a human: 

Loops are another way to interact with an API. For example, there’s one Kandji script that uses a for loop to iterate over a list to find the correct computer and then prompts the user to enter its asset tag. Another Kandji script loops through a provided CSV file to update a device record, such as its Blueprint, asset tag, or assigned user. 

Of course, there’s plenty more to know about APIs and how they can help you manage Apple devices. And there are plenty of online resources out there that'll teach you what you need to know. We hope the concepts and examples outlined above will motivate you to get out there and learn more about these ideas and how to implement them. MDM solutions such as Kandji are powerful tools on their own. But knowing how to use APIs to automate repetitive tasks, gather data, or make changes to multiple devices can expand their management capabilities dramatically.

About Kandji

Kandji fully supports APIs for managing and securing your Apple fleet. Documentation of that support can be found in the Kandji API support article. More specifics can be found at api.kandji.io and in our GitHub support repository. With support for APIs, as well as things like zero-touch deployment, one-click compliance, and offline remediation, Kandji is a great way to enroll, configure, and secure your devices.