OTA API Endpoints

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:

Before You Begin

Problem Description

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.

Approach

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.

Prerequisites

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:

  • Understand how Afero authorization API (OAuth) works. To read about OAuth, go to OAuth.net documentation. Also please read Cloud API.
  • Base Cloud API URL: https://api.afero.io.
  • Understanding of JSON and common HTTP methods POST, PUT, GET, and DELETE and their usage in the context of RESTful web services.
  • Be familiar with public OAuth/User API Endpoints and Device API Endpoints.
  • Understanding of how to authenticate with the Afero Cloud and how to use authorization tokens in subsequent requests.
  • Client credentials as described in RFC6749 Section 2 for client application authentication.

In production applications, do not use developer credentials obtained through the Afero Profile Editor!


General Notes on Using the OTA API Endpoints

  • Optional fields can be omitted from request payloads and are omitted from response bodies returned by the service.
  • All endpoints returning a list of objects return a paged result set. The default page size is 50 objects.
    • The contents of the result set can be influenced by using paging-related query parameters, such as page number (zero-based index), page size, and sort information (field and sort direction).
    • The result set object contains information about the total number of elements, total number pages, number of elements in the result set, and the objects themselves. This information can be used to implement a paging mechanism in clients.
  • Path parameters are always required. They are enclosed by two curly braces {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.

Firmware Type Endpoints

This section lists the endpoints that manage firmware types. Make sure you have read About Firmware Types.

POST /v1/ota/partners/{partnerId}/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
{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "name": "<string>",
 "description": "<string, optional>",
 "type": <integer>
}
Response Body Model Schema
{
 "id": "<integer_string>",
 "name": "<string>",
 "description": "<string, optional>",
 "type": <integer>,
 "partnerId": "<string>",
 "createdTimestamp": <integer>,
 "updatedTimestamp": <integer>,
 "versionAttributeId": <integer>
}

GET /v1/ota/partners/{partnerId}/types

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
[
 {
  "id": "<integer_string>",
  "name": "<string>",
  "description": "<string, optional>",
  "type": <integer>,
  "partnerId": "<string>",
  "createdTimestamp": <integer>,
  "updatedTimestamp": <integer>,
  "versionAttributeId": <integer>
 }
]

GET /v1/ota/partners/{partnerId}/types/{type}

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
[
 {
  "id": "<integer_string>",
  "name": "<string>",
  "description": "<string, optional>",
  "type": <integer>,
  "partnerId": "<string>",
  "createdTimestamp": <integer>,
  "updatedTimestamp": <integer>,
  "versionAttributeId": <integer>
 }
]

PUT /v1/ota/partners/{partnerId}/types/{type}

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
{
 "Content-Type": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "name": "<string>",
 "description": "<string, optional>"
}

Firmware Pool Image Endpoints

This section lists the endpoints that manage images in the firmware pool. Make sure you have read About Firmware Pools and Associations.

POST /v1/ota/partners/{partnerId}/pool

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
{
 "Content-Type": "application/json",
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "name": "<string>",
 "description": "<string, optional>",
 "type": <integer>
 "version": "<string>",
 "url": "<string>",
 "tags": ["<string, optional>"],
 "associations": {
  "key1": ["<string, optional>", "..."]
 }
}
Response Body Model Schema
{
 "id": "<integer_string>",
 "name": "<string>",
 "description": "<string, optional>",
 "type": <integer>,
 "partnerId": "<string>",
 "createdTimestamp": <integer>,
 "updatedTimestamp": <integer>,
 "versionAttributeId": <integer>
}

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.

POST /v1/ota/partners/{partnerId}/binaries

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
{
 "Content-Type": ["application/octet-stream", "multipart/form-data"],
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "value": "<string>"
}

Notes

  • The API offers two methods to upload a file:
    • Upload via a file stream using the content type application/octet-stream, or
    • Upload via a web browser-style file upload using multipart/form-data.
  • The returned value is a file identifier of the uploaded file in a temporary location. It the SHA-256 hash of the file.

POST /v1/ota/partners/{partnerId}/binaries/moveToRepository

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
{
 "Content-Type": "application/json",
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "value": "<string>",
}
Response Body Model Schema
{
 "value": "<string>"
}

Notes

  • Use the response body from the file upload endpoint as the payload.
  • The response body will contain the URL of the firmware binary in the firmware repository. This URL should be used to update the respective firmware pool record; otherwise, the service will not be able to send OTAs.

GET /v1/ota/partners/{partnerId}/pool

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "number": <integer>,
 "size": <integer>,
 "totalPages": <integer>,
 "numberOfElements": <integer>,
 "totalElements": <integer>,
 "content": [
  {
   "id": "<string_integer>",
   "name": "<string>",
   "description": "<string, optional>",
   "type": <integer>,
   "versionNumber": "<string_integer>",
   "version": "<string>",
   "url": "<string>",
   "tags": ["<string, optional>", "..."],
   "createdTimestamp": <integer>,
   "updatedTimestamp": <integer>,
   "partnerId": "<string>"
  }
 ],
 "sort": "<string>"
}

GET /v1/ota/partners/{partnerId}/pool/types/{type}

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "number": <integer>,
 "size": <integer>,
 "totalPages": <integer>,
 "numberOfElements": <integer>,
 "totalElements": <integer>,
 "content": [
  {
   "id": "<string_integer>",
   "name": "<string>",
   "description": "<string, optional>",
   "type": <integer>,
   "versionNumber": "<string_integer>",
   "version": "<string>",
   "url": "<string>",
   "tags": ["<string, optional>", "..."],
   "createdTimestamp": <integer>,
   "updatedTimestamp": <integer>,
   "partnerId": "<string>"
  }
 ],
 "sort": "<string>"
}

GET /v1/ota/partners/{partnerId}/pool/types/{type}/names/{name}/versions/{version}/exists

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "value": <boolean>,
}

Notes

  • Retrieves all device type associations of a given firmware image.

GET /v1/ota/partners/{partnerId}/pool/types/{type}/versionNumbers/{versionNumber}/associations

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
[
 {
  "name": "<string>",
  "partnerId": "<string>"
  "email": "<string>",
  "deviceTypeId": "<string>",
  "deviceTypeName": "<string>",
  "firmwareImageId": "<string_integer>"
 }
],

PUT /v1/ota/partners/{partnerId}/pool/types/{type}/versionNumbers/{versionNumber}

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
{
 "Content_Type": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "name": "<string>",
 "description": "<string, optional>",
 "version": "<string>",
 "url": "<string>",
 "tags": ["<string, optional>", "..."]
}

Firmware Image Endpoints

This section lists the endpoints that manage firmware images.

POST /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages

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
{
 "Content_Type": "application/json",
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "name": "<string>",
 "description": "<string, optional>",
 "type": "<integer>",
 "versionNumber": "<string>",
 "version": "<string>",
 "url": "<string>",
 "tags": ["<string, optional>", "..."],
 "associations": {
  "key1": ["<string, optional>", "..."]
 }
}
Response Body Model Schema
{
 "id": "<string>",
 "name": "<string>",
 "description": "<string, optional>",
 "type": "<integer>",
 "versionNumber": "<string>",
 "version": "<string, optional>",
 "url": "<string>",
 "tags": ["<string, optional>", "..."],
 "createdTimestamp": "<integer>",
 "updatedTimestamp": "<integer>",
 "partnerId": "<string>",
 "deviceTypeId": "<string>"
}

Notes

  • This endpoint creates an association between a generic firmware image record in the firmware pool with a specific device type. Thus, the versionNumber field is a required field in this request payload.
  • It is recommended that you use the same object as request payload as is returned from one of the GET endpoints in the Firmware Pool namespace. Modifying the payload from the original pool record will cause errors and prevent OTAs from succeeding!

GET /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "number": <integer>,
 "size": <integer>,
 "totalPages": <integer>,
 "numberOfElements": <integer>,
 "totalElements": <integer>,
 "content": [
  {
   "id": "<string>",
   "name": "<string>",
   "description": "<string, optional>",
   "type": <integer>,
   "versionNumber": "<string_integer>",
   "version": "<string, optional>",
   "url": "<string>",
   "tags": ["<string, optional>", "..."],
   "createdTimestamp": <integer>,
   "updatedTimestamp": <integer>,
   "partnerId": "<string>",
   "deviceTypeId": "<string>",
   "deviceDescriptionId": "<string>",
   "deviceProfileId": "<string>"
  }
 ],
 "sort": "<string>"
}

Notes

  • This endpoint retrieves a paged result set of associated firmware image records for a specific device type.
  • The firmware image records of type 4 (DEVICE_DESCRIPTION) will have two additional fields that identify the related entities that make up a device Profile in the Afero Platform.

GET /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "number": <integer>,
 "size": <integer>,
 "totalPages": <integer>,
 "numberOfElements": <integer>,
 "totalElements": <integer>,
 "content": [
  {
   "id": "<string>",
   "name": "<string>",
   "description": "<string, optional>",
   "type": <integer>,
   "versionNumber": "<string_integer>",
   "version": "<string, optional>",
   "url": "<string>",
   "tags": ["<string, optional>"],
   "createdTimestamp": <integer>,
   "updatedTimestamp": <integer>,
   "partnerId": "<string>",
   "deviceTypeId": "<string>"
  }
 ],
 "sort": "<string>"
}

Notes

  • This endpoint retrieves the associated firmware image records for a specific device type and firmware type.

GET /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}/versionNumbers/{versionNumber}

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
{
 "id": "<string_integer>",
 "name": "<string>",
 "description": "<string, optional>",
 "type": <integer>,
 "versionNumber": "<string_integer>",
 "version": "<string, optional>",
 "url": "<string>",
 "tags": ["<string, optional>"],
 "createdTimestamp": <integer>,
 "updatedTimestamp": <integer>,
 "partnerId": "<string>",
 "deviceTypeId": "<string>"
}

Notes

  • This endpoint retrieves one associated firmware image records for a specific device type and firmware type and version number.

PUT /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/{firmwareImageId}/push

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
{
 "Content-Type": "application/json",
 "Authorization": "Bearer <access_token>"
}
Request Payload Model Schema
{
 "value": "<string>"
}

Notes

  • The payload contains the device ID of the target device.

DELETE /v1/ota/partners/{partnerId}/deviceTypes/{deviceTypeId}/firmwareImages/types/{type}/versionNumbers/{versionNumber}

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
{
 "Authorization": "Bearer <access_token>"
}

Notes

  • Dissociates a firmware image from a device type.

Firmware Tag Endpoints

GET /v1/ota/partners/{partnerId}/tags

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
{
 "Accept": "application/json",
 "Authorization": "Bearer <access_token>"
}
Response Body Model Schema
["<string>", "..."]