REST API Reference

Live Documentation

https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/api-docs.png

A general live API documentation (following the OpenAPI specification) at /api/v1/docs/.

Browsable Web Interface

https://raw.githubusercontent.com/openwisp/openwisp-firmware-upgrader/docs/docs/images/api-ui.png

Additionally, opening any of the endpoints listed below directly in the browser will show the browsable API interface of Django-REST-Framework, which makes it even easier to find out the details of each endpoint.

Authentication

See openwisp-users: authenticating with the user token.

When browsing the API via the Live Documentation or the Browsable Web Interface, you can also use the session authentication by logging in the django admin.

Pagination

All list endpoints support the page_size parameter that allows paginating the results in conjunction with the page parameter.

GET /api/v1/firmware-upgrader/build/?page_size=10
GET /api/v1/firmware-upgrader/build/?page_size=10&page=2

Filtering by Organization Slug

Most endpoints allow to filter by organization slug, e.g.:

GET /api/v1/firmware-upgrader/build/?organization=org-slug

List of Endpoints

Since the detailed explanation is contained in the Live Documentation and in the Browsable Web Interface of each point, here we'll provide just a list of the available endpoints, for further information please open the URL of the endpoint in your browser.

List Mass Upgrade Operations

GET /api/v1/firmware-upgrader/batch-upgrade-operation/

Available filters

The list of batch upgrade operations provides the following filters:

  • build (Firmware build ID)

  • status (One of: idle, in-progress, success, failed)

Here's a few examples:

GET /api/v1/firmware-upgrader/batch-upgrade-operation/?build={build_id}
GET /api/v1/firmware-upgrader/batch-upgrade-operation/?status={status}

Get Mass Upgrade Operation Detail

GET /api/v1/firmware-upgrader/batch-upgrade-operation/{id}/

List Firmware Builds

GET /api/v1/firmware-upgrader/build/

Available filters

The list of firmware builds provides the following filters:

  • category (Firmware category ID)

  • version (Firmware build version)

  • os (Firmware build os identifier)

Here's a few examples:

GET /api/v1/firmware-upgrader/build/?category={category_id}
GET /api/v1/firmware-upgrader/build/?version={version}
GET /api/v1/firmware-upgrader/build/?os={os}

Create Firmware Build

POST /api/v1/firmware-upgrader/build/

Get Firmware Build Details

GET /api/v1/firmware-upgrader/build/{id}/

Change Details of Firmware Build

PUT /api/v1/firmware-upgrader/build/{id}/

Patch Details of Firmware Build

PATCH /api/v1/firmware-upgrader/build/{id}/

Delete Firmware Build

DELETE /api/v1/firmware-upgrader/build/{id}/

Get List of Images of a Firmware Build

GET /api/v1/firmware-upgrader/build/{id}/image/

Available filters

The list of images of a firmware build can be filtered by using type (any one of the available firmware image types).

GET /api/v1/firmware-upgrader/build/{id}/image/?type={type}

Upload New Firmware Image to the Build

POST /api/v1/firmware-upgrader/build/{id}/image/

Get Firmware Image Details

GET /api/v1/firmware-upgrader/build/{build_id}/image/{id}/

Delete Firmware Image

DELETE /api/v1/firmware-upgrader/build/{build_id}/image/{id}/

Download Firmware Image

GET /api/v1/firmware-upgrader/build/{build_id}/image/{id}/download/

Perform Batch Upgrade

Upgrades all the devices related to the specified build ID.

POST /api/v1/firmware-upgrader/build/{id}/upgrade/

Dry-run Batch Upgrade

Returns a list representing the DeviceFirmware and Device instances that would be upgraded if POST is used.

Device objects are indicated only when no DeviceFirmware object exists for a device which would be upgraded.

GET /api/v1/firmware-upgrader/build/{id}/upgrade/

List Firmware Categories

GET /api/v1/firmware-upgrader/category/

Create New Firmware Category

POST /api/v1/firmware-upgrader/category/

Get Firmware Category Details

GET /api/v1/firmware-upgrader/category/{id}/

Change the Details of a Firmware Category

PUT /api/v1/firmware-upgrader/category/{id}/

Patch the Details of a Firmware Category

PATCH /api/v1/firmware-upgrader/category/{id}/

Delete a Firmware Category

DELETE /api/v1/firmware-upgrader/category/{id}/

List Upgrade Operations

GET /api/v1/firmware-upgrader/upgrade-operation/

Available filters

The list of upgrade operations provides the following filters:

  • device__organization (Organization ID of the device)

  • device__organization_slug (Organization slug of the device)

  • device (Device ID)

  • image (Firmware image ID)

  • status (One of: in-progress, success, failed, aborted)

Here's a few examples:

GET /api/v1/firmware-upgrader/upgrade-operation/?device__organization={organization_id}
GET /api/v1/firmware-upgrader/upgrade-operation/?device__organization__slug={organization_slug}
GET /api/v1/firmware-upgrader/upgrade-operation/?device={device_id}
GET /api/v1/firmware-upgrader/upgrade-operation/?image={image_id}
GET /api/v1/firmware-upgrader/upgrade-operation/?status={status}

Get Upgrade Operation Details

GET /api/v1/firmware-upgrader/upgrade-operation/{id}

List Device Upgrade Operations

GET /api/v1/firmware-upgrader/device/{device_id}/upgrade-operation/

Available filters

The list of device upgrade operations can be filtered by status (one of: in-progress, success, failed, aborted).

GET /api/v1/firmware-upgrader/device/{device_id}/upgrade-operation/?status={status}

Create Device Firmware

Sending a PUT request to the endpoint below will create a new device firmware if it does not already exist.

PUT /api/v1/firmware-upgrader/device/{device_id}/firmware/

Get Device Firmware Details

GET /api/v1/firmware-upgrader/device/{device_id}/firmware/

Change Details of Device Firmware

PUT /api/v1/firmware-upgrader/device/{device_id}/firmware/

Patch Details of Device Firmware

PATCH /api/v1/firmware-upgrader/device/{device_id}/firmware/

Delete Device Firmware

DELETE /api/v1/firmware-upgrader/device/{device_pk}/firmware/