This document outlines the changes to the BitBrew platform and management APIs coming in our next release, March 31, 2017. Although there are no breaking changes that affect user applications, there are changes to existing endpoints and new endpoints that should be carefully read and understood.

BitBrew's API documentation will be updated when the release has been successfully deployed to our production environment.

Table of Contents

Device Update Failure Limits

The system will now cancel any device update after three failed attempts. This limit applies to both firmware and configuration updates, and failed attempts are counted independently for each type of file.

View and Set Update Failure Limit

Users may specify a tenant-wide failure limit other than the system default of three. They can also check the limit they've set.

New Endpoints

[PUT] ../v1/tenants/{tenantId}/devices/files
+ Request Body
{
   "updateFailureLimit": 2
}
[GET] ../v1/tenants/{tenantId}/devices/files
+ Response Body
{
    "updateFailureLimit": 2
}

If a device has already reached the update failure limit, increasing the tenant limit will not trigger retries for that device. The status must be reset manually through a different API call.

New Endpoint: Device File Status

The old device file state endpoint has been replaced by a new status endpoint:

- [GET] /v1/tenants/{tenantId}/devices/{deviceId}/files/state
+ [GET] /v1/tenants/{tenantId}/devices/{deviceId}/files/status
  1. The new endpoint uses different field names and a different structure.

  2. A field called updateFailureLimitReached has been added to the firmware and configuration objects with a boolean value.

  3. When the boolean value for updateFailureLimitReached is true, a new value appears in the status field called updateCancelled.

These are breaking changes.

Old Response Body

{
  "deviceId": "602091918",
  "deviceFilesWithStatus": [
    {
      "fileType": "configuration",
      "fileId": "test-configs",
      "version": "LGRTCS.05",
      "status": "uptodate"
    },
    {
      "fileType": "firmware",
      "fileId": "friends-and-family-fw",
      "version": "LGRTFS.04",
      "status": "updateCommandReceived"
    }
  ]
}

New Response Body

{
  "deviceId": "602091918",
  "configurationInfo": {
     "folderName": "test-configs",
      "activeFileName": "LGRTCS.05",
      "status": "uptodate",
      "updateFailureLimitReached": false
   },
   "firmwareInfo": {
      "folderName": "friends-and-family-fw",
      "activeFileName": "LGRTFS.04",
      "status": "updateCancelled",
      "updateFailureLimitReached": true
    }
}

Reset the Retry Status for a Device

New Endpoints

[POST] /v1/tenants/{tenantId}/devices/{deviceId}/configuration/retryStatus/reset
+ Request Body
{}
[POST] /v1/tenants/{tenantId}/devices/{deviceId}/firmware/retryStatus/reset
+ Request Body
{}

Clearing the retry status for a device will reset the updateFailureLimitReached field in the device file status endpoint to false and the status to notConnectedYet. These statuses are also automatically reset when a new folder is assigned to a device.

Metrics Endpoints

Query Number of Incoming Events and Outgoing Actions

See the number of incoming events or outgoing actions for a specified duration and interval.

New Endpoints

[GET] /v1/tenants/{tenantId}/metrics/events
[GET] /v1/tenants/{tenantId}/metrics/actions

Mandatory Query Parameters:

  • from - The start of the period to measure. Accepts absolute and relative time parameters.

  • interval - The length of time for each data point.

Relative time is a length of time since the current time. It is always preceded by a minus sign (-) and followed by a unit of time. Valid units of time:

Did this answer your question?