Before you begin, make sure you have read the background sections in Over-the-Air (OTA) Updates API. Below, you’ll find all the endpoint details, organized as follows:
Similar to any other software in development, firmware is usually set up in CD/CI fashion to streamline development and deployments; i.e., commits to source control trigger builds, which produce artifacts, which are then stored in an artifact repository for testing by QA. While Afero offers a web application to manage firmware images it requires manual interaction.
Depending on the partner’s internal development and build processes, the usage of the APIs for creating and managing firmware records can differ. This document will highlight some common use cases and show how the different APIs can be used to accommodate different development processes. This page will document first the different API endpoints and then describe in detail different use cases and how the APIs are used in each case and why.
Afero account authentication flow follows the OAuth 2.0 standard as described in RFC6749. The API documentation uses JSON format for data model examples. The full prerequisites are listed below:
In production applications, do not use developer credentials obtained through the Afero Profile Editor!
{parameter}
in the path of the resource for identification purposes. All other request parameters are query parameters. Required parameters are highlighted in bold.Certain IDs and integer values returned by the API are represented as strings. For example, the id and versionNumber fields are such instances. They are represented as strings as they may exceed common ranges for numbers, especially in JavaScript, whose whole integers are only precise up to 53 bits.
If arithmetic operations need to be performed on these values, they can be converted using a library or type that supports arbitrary-precision integers; i.e., the BigInteger type in Java, the big-integer package, or BigInt type in JavaScript. These fields are annotated as "<integer_string>"
in the model schemas.
This section lists the endpoints that manage firmware types. Make sure you have read About Firmware Types.
Creates a new partner firmware type.
Resource URL | /v1/ota/partners/{partnerId}/types
|
HTTP Method | POST
|
Response Code | 201 (CREATED) |
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
|
Response Body Model Schema | |
{ |
Retrieves partner firmware types.
Resource URL | /v1/ota/partners/{partnerId}/types
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Response Body Model Schema | |
[ |
Retrieves a firmware type, by type.
Resource URL | /v1/ota/partners/{partnerId}/types/{type}
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
Request Headers | |
{ |
|
Response Body Model Schema | |
[ |
Updates a partner firmware type.
Resource URL | /v1/ota/partners/{partnerId}/types/{type}
|
HTTP Method | PUT
|
Response Code | 204 (No Content) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
This section lists the endpoints that manage images in the firmware pool. Make sure you have read About Firmware Pools and Associations.
Creates a new firmware record in the firmware image pool.
Resource URL | /v1/ota/partners/{partnerId}/pool
|
HTTP Method | POST
|
Response Code | 201 (Created)
|
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
|
Response Body Model Schema | |
{ |
Notes
The associations
field in the request payload is optional. The “key” is the partner ID, the values are an array of device type IDs. A typical payload would look as follows:
"associations": { "partnerId1": ["deviceTypeId1", "deviceTypeId2"], "partnerId2": ["deviceTypeIdA", "deviceTypeIdB"] }
Associations can be created or deleted any time after a firmware image has been created in the pool.
Uploads a firmware file to a temporary location.
Resource URL | /v1/ota/partners/{partnerId}/binaries
|
HTTP Method | POST
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Notes
application/octet-stream
, ormultipart/form-data
.Moves a file from the temporary location to the permanent firmware image repository.
Resource URL | /v1/ota/partners/{partnerId}/binaries/moveToRepository
|
HTTP Method | POST
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
|
Response Body Model Schema | |
{ |
Notes
Retrieves some firmware images from the pool.
Resource URL | /v1/ota/partners/{partnerId}/pool
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
tags |
Comma-separated list of tags on which to filter. |
page |
Zero-based index of page to retrieve. |
size |
The number of elements per page. |
sort |
The field and sort direction; e.g., updatedTimestamp , description . |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Retrieves some firmware images of a specific type from the pool.
Resource URL | /v1/ota/partners/{partnerId}/pool/types/{type}
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
tags |
Comma-separated list of tags on which to filter. |
page |
Zero-based index of page to retrieve. |
size |
The number of elements per page. |
sort |
The field and sort direction; e.g., updatedTimestamp , description . |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Checks if a firmware image with given type, name, and version already exists in the pool.
Resource URL | /v1/ota/partners/{partnerId}/pool/types/{type}/names/{name}/versions/{version}/exists
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
{name} |
The name of the firmware image. |
{version} |
The version string of the firmware image. |
excludeFirmwareImageId |
The ID of a record to be excluded. Here, clients can use the ID of a record that is about to be updated to verify that no other record with this information already exists. |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Notes
Retrieves all device type associations of a given firmware image.
Resource URL | /v1/ota/partners/{partnerId}/pool/types/{type}/versionNumbers/{versionNumber}/associations
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
{versionNumber} |
The version number of the firmware image. |
Request Headers | |
{ |
|
Response Body Model Schema | |
[ |
Updates a firmware image in the pool.
Resource URL | /v1/ota/partners/{partnerId}/pool/types/{type}/versionNumbers/{versionNumber}
|
HTTP Method | PUT
|
Response Code | 204 (No Content) |
Request Parameters | |
{partnerID} |
The partner ID. |
{type} |
The firmware type. |
{versionNumber} |
The version number of the firmware image. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
This section lists the endpoints that manage firmware images.
Creates a new firmware image association with a device type.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages
|
HTTP Method | POST
|
Response Code | 201 (Created) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceTypeId} |
The device type ID. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
|
Response Body Model Schema | |
{ |
Notes
versionNumber
field is a required field in this request payload.Retrieves some firmware images.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceType} |
The device type ID. |
tags |
Comma-separated list of tags on which to filter. |
page |
Zero-based index of page to retrieve. |
size |
The number of elements per page. |
sort |
The field and sort direction; e.g., updatedTimestamp , description . |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Notes
Retrieves some firmware images by type.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceType} |
The device type ID. |
{type} |
The firmware type. |
tags |
Comma-separated list of tags on which to filter. |
page |
Zero-based index of page to retrieve. |
size |
The number of elements per page. |
sort |
The field and sort direction; e.g., updatedTimestamp , description . |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Notes
Retrieves a firmware image by type and version number.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}/versionNumbers/{versionNumber}
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceTypeID} |
The device type ID. |
{type} |
The firmware type. |
{versionNumber} |
The version number of the firmware image. |
page |
Zero-based index of page to retrieve. |
size |
The number of elements per page. |
sort |
The field and sort direction; e.g., updatedTimestamp , description . |
Request Headers | |
{ |
|
Response Body Model Schema | |
{ |
Notes
Pushes a firmware image to a device.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/{firmwareImageId}/push
|
HTTP Method | PUT
|
Response Code | 202 (Accepted) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceTypeID} |
The device type ID. |
{firmwareImageId} |
The ID of the firmware image to push to a device. |
Request Headers | |
{ |
|
Request Payload Model Schema | |
{ |
Notes
Pushes a firmware image to a device.
Resource URL | /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}/versionNumbers/{versionNumber}
|
HTTP Method | PUT
|
Response Code | 204 (No Content) |
Request Parameters | |
{partnerID} |
The partner ID. |
{deviceTypeID} |
The device type ID. |
{type} |
The firmware type. |
{versionNumber} |
The version number of the firmware image. |
Request Headers | |
{ |
Notes
Retrieves all firmware tags.
Resource URL | /v1/ota/partners/{partnerId}/tags
|
HTTP Method | GET
|
Response Code | 200 (OK) |
Request Parameters | |
{partnerID} |
The partner ID. |
Request Headers | |
{ |
|
Response Body Model Schema | |
["<string>", "..."] |