Upgrade 3.8 to 3.9

Simplified labels for devices by removing the key and keeping only value

Usage Example

Before this change, device labels were key value pairs. Every key could be assigned once per device:

CODE

{
  {
    "id": "manufacturer:nke",
    "key": "manufacturer",
    "value": "nke"
  },
  {
    "id": "measurement:temperature",
    "key": "measurement",
    "value": "temperature"
  },
  {
    "id": "location:office",
    "key": "location",
    "value": "office"
  }
}

With version 3.8 and later, labels are simple strings, more akin to tags:

CODE

{
  "nke",
  "temperature",
  "office"
}

Migration of existing data

Existing labels are migrated to the new schema by concatenating key and value with an underscore:

Required actions

Consumers of the REST-API need to adapt their data model as described above.
Queries to the REST API which use query parameters to filter by device labels need to be adapted to use the new style of labels.

Added endpoints for easily creating/updating/deleting labels on a device

Usage example

Up to version 3.7, labels were managed using the API endpoint for the device which they label:

CODE

PUT /api/v3/devices/:device-id
{
  "labels": [
    {
      "key": "X",
      "value": "Y"
    },
    {
      "key": "A",
      "value": "B"
  ]
}

Starting with version 3.8, labels are managed with dedicated endpoints using the CRUD pattern. E.g. labels are created with the verb POST to the resource /api/v3/device/:id/labels:

CODE

POST /api/v3/devices/:device-id/labels?labels=foo,bar

Retrieving labels

CODE

GET /api/v3/devices/:device-id/labels

Deleting a label:

CODE

DELETE /api/v3/devices/:device-id/labels/:label-id

Data migration

Not applicable.

Required actions

Consumers of the REST API need to be migrated to the new interface.

Added selectors for integrations that will match devices labels

Previously, device selection happened by an integration's label.

CODE

{
  "labels": [
    {
      "key": "foo",
      "value": "bar"
    },
    {
      "key": "myxl",
      "value": "plyx"
    }
  ],
  ...
}

From 3.6 on device selection happens by dedicated selectors.

As of now, only logical disjunction (with $or is supported).

CODE

{
  "selectors": {
    "$or": [
      "foo_bar",
      "myxl_plyx",
    ]
  },
  ...
}

Data migration

Not applicable.

Required actions

Consumers of the REST API need to be migrated to the new interface.

Disabled public endpoints for device information and device activation

To the best of our knowledge, this API has not been in use.

Required actions

Adapt consumers of the REST API to manually create devices.