Breaking Changes in thingsHub 5.1

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

Changes to the /api/v3/devices/{id}/telemetry endpoint:

GET, PUT responses for /api/v3/devices/{id}/telemetry:

The response structure for GET and PUT requests to /api/v3/devices/{id}/telemetry has been updated:

1. Before:

   CODE

   {
     "config": {
       "latitude": "latitude",
       "longitude": "longitude"
     },
     "data": {
       "latitude": 37.7749,
       "longitude": -122.4194
     },
     "profile": "static"
   }

2. After:

   CODE

   {
     "config": {
       "fields": {
         "latitude": "latitude",
         "longitude": "longitude"
       },
       "initial_latitude": 37.7749,
       "initial_longitude": -122.4194,
       "initial_timestamp": "2024-07-08T18:38:15.214Z"
     },
     "data": {
       "latitude": 37.7749,
       "longitude": -122.4194
     },
     "last_position_at": "2024-07-08T18:38:15.214Z",
     "profile": "static",
     "updated_at": "2024-07-08T18:38:15.214Z"
   }

Key changes:

• The response now includes additional fields under config (fields, initial_latitude, initial_longitude, initial_timestamp), last_position_at, and updated_at.

• The config fields are now in the field fields inside config instead of just being in the config object, which is a breaking change

Changes to the /api/v3/journey-entries endpoint:

• query param journey_id in LIST endpoint changed to journey_uuid:

  The query parameter journey_id in the LIST endpoint /api/v3/journey-entries has been renamed to journey_uuid.

Changes to the /api/v3/journeys endpoint:

• Field id changed to uuid in Listing response objects:

  The field id in objects returned by the /api/v3/journeys Listing endpoint has been renamed to uuid.

Breaking helm changes:

Only for On-Premise Customers

• Notifier
  ThingsHub introduced the central notification service - the thingsHub Notifier with this release, which all on-prem customers will have to deploy. Consequently, a new notifier block has been added to the tenant configuration file.
  For details on what changes to make to the tenant configuration file to accomodate this, please consult the thingsHub upgrade guide for version 5.1: Upgrade to 5.1 | Update-Tenant-Configuration

• Setting up the Notifier service
  For instructions on how to set up the cluster-wide Notifier service, consult the thingsHub official documentation on the Notifier service: https://docs.smartmakers.io/thingshub4/notifier-notification-service

Required Actions:

• Update your application to handle the enhanced response structure from the /api/v3/devices/{id}/telemetry endpoint.

• Adjust any code that interacts with /api/v3/journey-entries to use journey_uuid instead of journey_id as the query parameter.

• Modify your application to access uuid instead of id when processing responses from the /api/v3/journeys endpoint.

• Change the tenant configuration file to include the notifier block in it.

Ensure these changes are implemented before upgrading to thingsHub 5.1 to avoid any disruptions in functionality.