Common use-cases with Device Management APIs

A detailed documentation of all available APIs can be found in Device Management API Documentation. Here are some basic use-cases.

• List all cameras claimed to an Azena account
• Claim a device to an Azena account
• List all cameras claimed via API
• Get a list of all available applications/licenses in your account
• Get number of available applications/licenses for specific application 
• Install application on online camera
• Install an application on offline camera
• Uninstalling applications from online camera
• Get all applications currently installed on online camera
• Starting and stoping an application
• Updating an application
• How to handle errors and retry failed requests
• How to handle batch requests

 

Some API endpoints require additional permissions and will not work out of the box with your Azena credentials. If you would like to make full use of our API suite, please contact support to request this additional functionality. It is possible to add additional permissions to your personal user account or to create a dedicated technical user for your company.

 

List all cameras claimed to an Azena account

Our Device Management API offers a possibility to list all cameras claimed to an Azena account. Please use the Device Management Tool or login to the camera web-frontend to claim a device to the Azena Cloud. A description on how to access camera web-frontend can be found in Connecting Cameras section.

 

Claim a device to an Azena account

Devices require an active internet connection in order to be claimed to the Azena Platform. More information on potential URL whitelisting can be found here. More information on how to claim a device can be found here.

 

List all cameras claimed via API

API: GET /devices/v1/devices

Returns a list of cameras claimed to the Azena account. Additional filters can be set in the query to limit the number of results.

Remarks:

• The maximum number of returned devices is currently limited to 1000. In case there are more devices claimed to your account, use the page query parameter until the API does not provide any devices anymore.
• Devices in state UNCLAIMED are devices that have installed licenses associated to your account, even if the devices themselves have not been claimed to your account before. This is used to keep track of your license usage also on offline devices.
• The returned deviceID is used to identify a device and is used to perform further API actions.

 

Get a list of all available applications/licenses in your account

API: GET /license/v1/licensequantities

Returns a list that contains the number of used and free license quantities per application and license type in your account. Application license quantities need to be bought via the Azena Application Store. 

 

Get number of available applications/licenses for specific application 

API: GET /license/v1/licensequantities/apps/{appId}

Returns the number of free and used quantities of licenses for a specific application ID and license type.

 

 

Install application on online camera

Step 1: Buy license type quantity for application ID

Application license quantities need to be bought via the Azena Application Store. 

Step 2: Check quantities for application and license type

See Get a list of all available applications/licenses in your account section.

Step 3: Get device ID

See List all cameras claimed via API section.

Step 4: Install application on device

API: PUT /software/v1/apps/{appId}/devices/{deviceId}

Installs the application on the device with the license type specified in payload (FULL, TRIAL, SUBSCRIPTION). Prerequisite is an existing free license quantity for the given license type and application ID and an active internet connection of the device.

 

Install an application on offline camera

Step 1: Buy license type quantity for application ID

Application license quantities need to be bought via the Azena Application Store. 

Step 2: Check quantities for application and license type

See Get a list of all available applications/licenses in your account section.

Step 3: Get device ID

For claimed devices: See List all cameras claimed via API section.

For offline devices: Use ONVIF Discovery.

Step 4: Check for existing license

Check whether a license for specific app and device combination already exists:

API: GET /license/v1/licenses/apps/{appId}/devices/{deviceId}

The response will be an array of license information, each including license ID, license token, application ID and license type.

Step 5: Generate new license (optional)

Generate a new license for a given application ID, device ID and license type. Remark: For license type SUBSCRIPTION, you also need to provide the order ID.

API: PUT /license/v1/licenses

Returns license information for the license created, including a unique license token. Each license has a unique license ID and is bound to a device ID and application ID.

Step 6: Download License

API: GET /license/v1/licenses/{licenseId}/token

Triggers download of a license file with given license ID.

Step 7: Download Application

API: GET /software/v1/apps/{appId}/download

Triggers download of the application .apk binary file.

Step 8: Upload Application and License on Device via ONVIF

Upload the license file and the .apk file on your camera via ONVIF API, see ONVIF server.

 

Uninstalling applications from online camera

API: DELETE /software/v1/apps/{appId}/devices/{deviceId}

Will uninstall an application from a device. This will automatically return the license to your Azena account.

 

Get all applications currently installed on online camera

API: GET /device/v1/devices/{deviceId}/apps

Returns all application IDs currently installed on a device with specified device ID.

 

Starting and stoping an application

Get application status for a device

API: GET /software/v1/apps/{appId}/devices/{deviceId}

Returns information about application installation state, application running state and whether the app is updatable.

Start or stop application

API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/RUNNING

Starts application on online device.

API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/NOT_RUNNING

Stops application on online device.

 

Updating an application

Follow the optional steps to get information which devices need to be updated.

Step 1: Get all devices with available application updates

With filter option you can query all devices in your account that have applications installed that can be updated.

API: GET /device/v1/devices?appsUpdatePossible=true

Step 2: Get all applications currently installed on device

API: GET /device/v1/devices/{deviceId}/apps

Returns all application IDs and application status for applications currently installed on a device.

Step 3: Check what application is updatable (optional)

API: GET /software/v1/apps/{appId}/devices/{deviceId}

Returns app status including information whether the app is updatable (true or false).

Step 4: Update app

API: POST /software/v1/apps/{appId}/devices/{deviceId}

Triggers an update of the given application to the latest version.

Step 5: Check success

You can execute Step 3 or 1 again to verify if the update was successful. Since the update can take several minutes you should wait long enough before executing this step.

 

How to handle errors and retry failed requests

When you send requests to the Device Management API you might encounter certain errors sometimes. They can be categorized into client errors (4xx error codes) and server errors (5xx error codes).

Client errors usually indicate problems that need to be fixed by the client, like missing authentication or missing parameters.

Server errors usually indicate problems like server maintenance that need to be resolved by Azena. You can retry the request until it succeeds.

error code	what does it mean
400	Bad request. Something is wrong with the request, e.g. a mandatory parameter is missing.
401,403	Access denied. Authorization is missing, wrong or expired.
404	Not found. The object could not be found or the url is wrong.
408	Timeout. There might be an issue with your network connection. Retry the request after a few seconds.
429	Too many requests. You are sending too many requests in a short period of time. Retry the request after a few seconds.
500,502,503,504	Server error. Retry the request after a few minutes. If the error persists contact support.

 

How to handle batch requests

If you want to install applications on multiple devices or if you want to update multiple applications there are a few things to consider.

Devices will start to download applications which might be quite large. So in order to not overwhelm your own network you should consider only installing/updating a small number of applications at once or even one-by-one. You might also run into timeouts or rate limiting while executing these requests, so robust error handling and retry policy needs to be implemented.

 

regular batch installation:

 

batch installtion with error handling: