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/statusThe new endpoint uses different field names and a different structure.
A field called
updateFailureLimitReachedhas been added to the firmware and configuration objects with a boolean value.When the boolean value for
updateFailureLimitReachedistrue, a new value appears in thestatusfield calledupdateCancelled.
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/actionsMandatory 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: