At the heart of the balena platform sits the API. Not only does the API facilitate communication between our backend services, it also serves as the primary interface for external applications. The API acts as a source of truth across services, devices, and fleets, and it powers our UI, CLI, and SDKs.
We recently updated our API documentation, giving you a better look at the information that is available to be queried and modified. To help you get the most from this new documentation, I’d like to walk you through a few examples, outlining the steps between a question about your fleet and the API call that will give you the answer.
Scenario 1
Our fleet has hundreds of devices. We know that at any given time, due to network limitations, some number of these devices could be offline. We’d like to build an external application that monitors for offline devices and sends notifications.
Where to start?
The API documentation includes a list of available resources in the balena backend model. Let’s take a look at the list to see what might be most relevant to our scenario:
We need to know about offline devices, so the Device resource is probably a good place to start. Selecting this value, we are given a list of the available fields for the Device resource. One of the fields is is_online, which should be exactly what we need:
Example call
Once we have the resource and fields we need, constructing an API call is straightforward. The base API endpoint, https://api.balena-cloud.com/v4/, is followed by the resource name, giving us https://api.balena-cloud.com/v4/device. To narrow things down, we’ll use the $filter method to only show offline devices, and the $select method to reduce the returned info to just the UUIDs:
https://api.balena-cloud.com/v4/device?$filter=is_online eq false&$select=uuid
Once we have the correct URL, we’ll be able to make a curl call by providing the appropriate headers:
curl -X GET \
"https://api.balena-cloud.com/v4/device?\$filter=is_online%20eq%20false&\$select=uuid" \
-H 'Authorization: Bearer <AUTH_TOKEN>' \
-H 'Content-Type: application/json'
You can read more about API authentication in our docs.
Scenario 2
We’ve used device tags to designate a portion of our fleet as high priority, using a tag key of priority and a value of high. After some discussion, we’ve decided we only want notifications for when high priority devices go offline.
Where to start?
After looking closely at the list of fields available for Device resources, we don’t see anything about tags. Undiscouraged, we take a fresh look at the list of available resources, and we realize there is a Device tag resource:
The Device tag resource doesn’t have a lot of fields, but we’ll end up using most of them: tag_key and value to find the high priority devices, and device to filter further for offline devices.
Example call
To make this call work, we’ll have to use a little boolean logic in our filter. Querying for device tags that have both a tag_key of priority AND a value of high looks like this:
https://api.balena-cloud.com/v4/device_tag?\$filter=tag_key eq 'priority' and value eq 'high'
But wait! There’s still one more thing we need to filter on. The is_online field comes from the Device resource, but because the Device tag resource links to a Device, we can easily filter on that field using this syntax: device/is_online. Here’s the URL so far:
https://api.balena-cloud.com/v4/device_tag?\$filter=tag_key eq 'priority' and value eq 'high' and device/is_online eq false
To return the device UUIDs, we’ll have to use one more method. When one resource is linked to another, the details of the linked resource can be displayed using the $expand method. In our scenario, this will look like $expand=device($select=uuid), which will allow us to return just the device UUIDs and none of the other device details. Putting it all together, we get:
curl -X GET \
"https://api.balena-cloud.com/v4/device_tag?\$filter=tag_key%20eq%20'priority'%20and%20value%20eq%20'high'%20and%20device/is_online%20eq%20false&\$expand=device(\$select=uuid)" \
-H 'Authorization: Bearer <AUTH_TOKEN>' \
-H 'Content-Type: application/json'
Conclusion
The balena API gives you access to a wealth of information about your fleet, allowing you to build external applications and interfaces that seamlessly integrate with your devices. Our documentation helps you construct API calls by providing the available resources and fields, as well as a number of examples. As always, if you find anything missing or have any troubles, let us know on the forums!
