Breaking changes in thingsHub 5.0

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

Deprecation of /api/v3/things endpoint, and migration to api/v3/tracked-assets

• All endpoints under the path api/v3/things have been deprecated and migrated to the api/v3/tracked-assets endpoint.

  • The following endpoints have been removed:

    • DELETE /api/v3/things/{id}/geolocation

    • PUT /api/v3/things/{id}/geolocation

• Breaking Changes to business object thing vs tracked-asset:

  • The external_id field has been renamed to tracker_id

  • The geolocation_history field has been removed from the object

• Comparison between the Thing object and Tracked Asset object:

{
      "created_at": "2024-07-09T11:24:34.252Z",
      "external_id": "HH SM 4711",
      "geolocation": {
        "latitude": 48.93470432050519,
        "longitude": 8.438669443130493,
        "moved_at": "2020-01-01T04:00:01Z",
        "site": "SmartMakers HQ",
        "speaking_location": "Parking Hallway,SmartMakers HQ",
        "zone": "Parking  Hallway"
      },
      "geolocation_history": [
        ...
        {
          "latitude": 48.934182767785245,
          "longitude": 8.44047725200653,
          "moved_at": "2020-01-01T01:00:01Z",
          "site": "SmartMakers HQ",
          "zone": "Parking  Lot"
        },
        ...
      ],
      "id": "my-car",
      "metadata": {
        "license": "HH SM 4711",
        "vin": "4Y1SL65848Z411439"
      },
      "name": "My Car",
      "type": "asset-tracker",
      "updated_at": "2024-07-09T11:24:34.252Z"
}

{
      "created_at": "2024-07-09T11:24:36.424Z",
      "tracker_id": "HH SM 4711",
      "geolocation": {
        "latitude": 48.93470432050519,
        "longitude": 8.438669443130493,
        "moved_at": "2020-01-01T04:00:01Z",
        "site": "SmartMakers HQ",
        "speaking_location": "Parking Hallway,SmartMakers HQ",
        "zone": "Parking  Hallway"
      },
      "id": "my-car",
      "metadata": {
        "license": "HH SM 4711",
        "vin": "4Y1SL65848Z411439"
      },
      "name": "My Car",
      "type": "asset-tracker",
      "updated_at": "2024-07-09T11:24:36.424Z",
       
      "active_journey_id": "123e4567-e89b-12d3-a456-426614174000",
      "entered_site_at": "2024-07-09T11:24:36.424Z",
      "exited_site_at": "2024-07-09T11:24:36.424Z",
      "site_id": "site-123",
      "site_name": "Site 123",
      "zone_id": "zone-123",
      "zone_name": "Zone 123"
}

• Changes to the API endpoints:

Please refer to the above table for the json description of the new Tracked Asset and the deprecated Thing objects.

Changes to the /api/v3/assets endpoint:

• The endpoint structure is simplified to match the format of a single asset object.

• Instead of accepting an array of asset objects, it accepts a single object containing the following fields:

  • description: Optional textual description of the asset.

  • id: Unique identifier for the asset.

  • metadata: Optional dictionary containing additional asset information.

  • name: Name of the asset.

• Comparison of the old and new payload:

  • Old:

    CODE

    [
      {
         "description": "Description of the asset",
         "id": "unique-id-of-asset",
         "metadata": {},
         "name": "Name of the Asset"
      }
    ]

  • New:

    CODE

    {
       "description": "Description of the asset",
       "id": "unique-id-of-asset",
       "metadata": {},
       "name": "Name of the Asset"
    }

• Changes to the /api/v3/things endpoint:

POST /api/v3/things endpoint is deprecated and replaced with the new POST /api/v3/tracked-assets endpoint. The new endpoint simplifies the payload structure by removing the redundant metadata field.

• Comparison of the old and new payload:

  • Old:

    CODE

    POST /api/v3/things
    {
          "external_id": "HH SM 4711",// ID of the Asset Tracker
          "id": "my-car",             // ID of the Asset
          "metadata": {               // Metadata of the asset copied for reference
              "license": "HH SM 4711",
              "vin": "4Y1SL65848Z411439"
          },
          "name": "My Car",           // Name of the Asset
          "type": "asset-tracker"     // ID of the Tracking Algorithm
      }

  • New:

    CODE

    POST /api/v3/tracked-assets
    {
          "tracker_id": "HH SM 4711", // ID of the Asset Tracker
          "id": "my-car",             // ID of the Asset
          "name": "My Car",           // Name of the Asset
          "type": "asset-tracker"     // ID of the Tracking Algorithm
      }

Helm Changes:

Only for On-Premise Customers

thingsHub 5.0 major release comes with many updates to the tenant configuration file, its structure and adds various new services which break the release unless their configuration set properly.
For the new tenant configuration file structure for your on-premise thingsHub installation, consult our documentation on the upgrade process to thingsHub 5.0: https://smartmakers.atlassian.net/wiki/x/BoCz1Q

Key changes:

• The metadata field is no longer required and will be automatically populated based on the id. This eliminates redundancy and simplifies the payload.

• The field name external_id has been changed to tracker_id for consistency with other API endpoints, and make it clear that the endpoint is for tracking use-case.

Required Actions

If the changes affect endpoints that the API consumers are using any of these endpoints, they should be updated to reflect the new structures:

• Adapt the tenant configuration file structure to the new structure required by thingsHub 5.

• For the /api/v3/assets adjust your code to send a single object instead of an array.

• For the /api/v3/things endpoint, all API endpoints under this should be migrated to the new /api/v3/tracked-assets endpoint and updated your payload as needed. In addition, the removed endpoints should now not be used.
  Please consult the table in this section for a detailed description of the changes.

Our dedicated support team is available to answer any questions and provide assistance during the migration process. Feel free to reach out to us.