Breaking Changes in thingsHub 5.5

This document describes the changes that a user must be aware of when upgrading from thingsHub 5.4 to thingsHub 5.5:

API Changes

Changes to the /api/v3/drivers endpoint:

1. Change in firmwareversion field to firmware_version:

   The firmwareversion field within the supports array has been renamed to firmware_version in all API responses (GET, PUT, POST, and LIST) related to drivers.

2. Pagination introduced in the Listing endpoint:

   The LISTing endpoint /api/v3/drivers now returns a paginated list of drivers instead of just a simple array.

   • Before:

     CODE

     [
       {
         "author": "John Doe",
         "description": "Driver for XYZ device",
         "digest": "abcdef123456",
         "labels": [
           {
             "key": "version",
             "value": "1.0"
           }
         ],
         "name": "XYZ Driver",
         "os": "Windows",
         "level": "1.0",
         "platform": "x86",
         "supports": [
           {
             "firmwareversion": "v1.2.3",
             "manufacturer": "XYZ Corp",
             "model": "XYZ-1000"
           }
         ],
         "tags": [
           "device",
           "driver"
         ]
       },
       ...
     ]

   • After:

     CODE

     {
       "count": 0,
       "page": 0,
       "total_count": 0,
       "total_pages": 0,
       "collection": [
         {
         "author": "John Doe",
         "description": "Driver for XYZ device",
         "digest": "abcdef123456",
         "labels": [
           {
             "key": "version",
             "value": "1.0"
           }
         ],
         "name": "XYZ Driver",
         "os": "Windows",
         "level": "1.0",
         "platform": "x86",
         "supports": [
           {
             "firmwareversion": "v1.2.3",
             "manufacturer": "XYZ Corp",
             "model": "XYZ-1000"
           }
         ],
         "tags": [
           "device",
           "driver"
         ]
       },
       ...
       ]
     }
     }

Key changes:

• The firmwareversion field in the supports array has been renamed to firmware_version for consistency.

• The endpoint /api/v3/drivers now returns a paginated response, providing additional metadata such as count, page, total_count, total_pages, and a collection of drivers.

Required Actions:

• Update your code to handle the firmware_version field instead of firmwareversion in API responses related to drivers.

• Adjust your application to accommodate paginated responses from the /api/v3/drivers endpoint. The items now are under the field "collection", instead of in the first level of the json response.

If your application uses any of these endpoints, make sure to integrate these changes before upgrading to thingsHub 5.5.

Breaking helm changes:

Only for On-Premise Customers

Addition of Google Maps API key to the iam block:
The tenant configuration now has a mandatory google maps API key section in it, which will have to be added in the iam block. You should add the iam.keys with the following structure to your tenant configuration file.

global
  ...
    ...
  ...
iam:
  keys:
    map:
      key: {GMAPS_API_KEY}
      id: {YOUR_GOOGLE_MAP_ID}
...

For more information on this API key and how to set Google APIs up for your on-premise thingsHub installation, go to our official docs on Google API Key Management: Google Maps and other geo-service API Keys

Integration Changes

This is only applicable to users who are using integrations (e.g. MQTT) to get thingsHub device data to external systems.

Key change:

• Support for the version field in the device message has been removed, since this is not give any information about the device. This field is always empty in thingsHub 5.5.

Required Action

• If any third party systems using data from thingsHub integrations have dependency on this version field , they will have to remove this dependency.