Balena API v7: New Features, Breaking Changes and Migration Guide 

From more detailed device status reporting to streamlined resource management, balena API v7 represents our mission to reduce friction for fleet owners. In this blog post, we will provide a concise overview of the new features and breaking changes introduced in this new major version of balena API.

What are balena API versioned endpoints?

At balena, we use semantic versioning which means that new features are introduced on minor version bumps and major version bumps are used when we have breaking changes on the API. We also maintain all the versioned endpoints (from v1 to the new v7) working exactly as they did before so that customers can continue to use older versions of the API without any disruptions. This ensures that our customers’ integrations remain stable, even as we introduce new features or make necessary changes.

There are several advantages to using the latest version (v7), including access to all of the new features described below, performance improvements, and better support as this is the version we use internally. All new features going forward will only be available on v7.

New features and migration tips

More comprehensive device status

Some of the values of the device.overall_status property have been changed as follows:

• offline is now renamed to disconnected.
• idle was split into two different properties, operational and reduced-functionality
  • operational means the device is connected both to the API and cloudlink. 
  • reduced-functionality means one of these connections is failing. 
• All the other statuses (configuring, inactive, post-provisioning, updating) stay the same.

Migration tip: Update your project to handle the new possible responses on that field. Read more about statuses of devices here.

Improved error handling on incorrect requests

Any API request doing $select or $expand on non-existent properties now throws a 4xx error rather than just ignoring them. This fixes the case of silent errors that existed in previous versions of our API, for example because of a typo in a $select list.

Migration tip: Update any such query in your project to only $select and $expand valid properties based on our documentation.

Fixes and Breaking changes

Behavior change for device.should_be_running__release

The property device.should_be_running__release still exists in v7 however it has a different behavior than before. The previous behavior for this field in v6 was to be used for pinning a device to a specific release. When left as null, the device would track the release that the fleet is tracking.

In v7 the field that offers that behavior is the more semantically named device.is_pinned_on__release field. On top of that we have a new read-only field device.should_be_running__release which is auto-filled with the release that the device is pinned to, or otherwise the release that the fleet is tracking. 

Migration tip: Replace all v6 device.should_be_running__release requests with device.is_pinned_on__release.

Bonus tip

In case in v6 you were using both device.should_be_running__release and application.should_be_running__release to reason what version the device is meant to be running, you might be able to just fetch the v7 device.should_be_running__release.

Example:

GET https://api.balena-cloud.com/v6/device(1) would output something like for a not pinned device:

{
  "d": [{
        …
        should_be_running__release: null,
    }] 
} 

GET https://api.balena-cloud.com/v7/device(1) will default the field to the running application release:

{
  "d": [{
        …
        should_be_running__release: 7, // Example ID of the release that the application is tracking
  }] 
} 

Actor resource cohesive behavior

The Actor resource now will operate as any of the OData resources in the platform, which means, when the response contains the actor navigation property it will be a { __id: number; } object instead of a direct number.

Migration tip: Update any client side code that expects a numeric actor in <some_resource>.actor to <some_resource>.actor.__id. The resources that have an actor property are: application, user & device.

Resources cleanup and name changes

Several fields that were already deprecated and returned empty or null (but still present on previous versions for backwards-compatibility) have been removed in v7. They were either internal-only experimental fields or previously deprecated features. We suggest you stop relying on them and move to the v7 equivalent.

The removed fields are:

• device.logs_channel
• device.vpn_channel
• device.is_managed_by__device
• device.manages__device
• device.downloads__image
• application.depends_on__application
• application.is_dependent_on_by__application
• The gateway_download resource

Migration tip: Stop using any of the properties above.

The replaced fields are:

• The device_history.should_be_running__release was replaced with the device_history.is_pinned_on__release similarly to the change on the device resource described earlier.
• Support for the convenience device_type field on POSTs to the device and application resource has been removed. In v6 we already offered the device.is_of__device_type and application.is_for__device_type fields as replacements, and in v7 these are the only way to reference or set the device type of devices & applications.
  Example:

curl -X POST "https://api.balena-cloud.com/v6/application" -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
    --data '{"app_name": "<NAME>", "organization": <ORGANIZATION_ID>, "device_type": 'raspberrypi5' }'

Now becomes

DEVICE_TYPE_ID=$(curl "https://api.balena-cloud.com/v7/device_type(slug='raspberrypi5')" -H "Content-Type: application/json" | jq -r '.d[0].id');
curl -X POST "https://api.balena-cloud.com/v7/application" -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
    --data "{\"app_name\": \"<NAME>\", \"organization\": <ORGANIZATION_ID>, \"is_for__device_type\": $DEVICE_TYPE_ID }"

https://docs.balena.io/reference/api/resources/fleet/#get-my-apps

• The release.release_type (‘final’/’draft’) field was removed in favor of release.is_final (boolean).
• The release.should_be_running_on__device was replaced by release.is_pinned_to__device.
• The my_application resource was replaced with a new is_directly_accessible_by__user term on the application resource:

Example:

curl --location 'https://api.balena-cloud.com/v6/my_application'  --header 'Authorization: Bearer $API_TOKEN'

Now becomes

curl --location 'https://api.balena-cloud.com/v7/application?$filter=is_directly_accessible_by__user/any(dau:true)' --header 'Authorization: Bearer $API_TOKEN'

https://docs.balena.io/reference/api/resources/fleet/#get-my-apps

• The supervisor_release resource was removed in favor of normal releases on public Supervisor Apps. You can find more information on how to retrieve them in our documentation page https://docs.balena.io/reference/api/resources/supervisor_release/
• As a result the device.should_be_managed_by__supervisor_release field was replaced with the device.should_be_managed_by__release field.

New required fields:

• POSTs to the application resource now require you to provide the organization field in the body, which should hold the ID of the organization that the fleet will be created in.

Other changes:

• We no longer automatically populate the response body with a status code message
  eg ‘OK’ for PATCH requests when the status code is 200.

How to migrate: Stop using any of the properties above and use the replacement when there is one.

Stay updated!

• For more details, visit our documentation page.
• If you have any questions or need assistance, please reach out to our team on support or the forums.

If you have any suggestions or features you would like to see, please drop us a line on our feature requests page.

The post Balena API v7: New Features, Breaking Changes and Migration Guide  appeared first on balena Blog.