Bosch IoT Device Management - will be discontinued by mid 2024

Merge attributes and features via Things HTTP API

In previous sections, managing attributes and features was demonstrates with a PUT thing request.

Bosch IoT Thing offers also the PATCH operation via HTTP API. The things resource and all of its sub-resources allow to merge an existing thing with the thing provided in the request payload by using the newly introduced HTTP PATCH method. Those parts that are not affected by the merge are not changed.

The request payload of such a merge update has to be provided in JSON merge patch format. In short, a JSON merge patch resembles the original JSON structure of a thing and the fields provided in the patch are added to or updated in the existing thing.

Please note however, that null values have a special meaning when applying a merge patch. A null value indicates the removal of existing fields in the updated thing. For more details and examples please refer to RFC-7396.


Goal

Let us assume, your hello world thing already has attributes and features and you want to just add a new attribute key-value as well as a new feature.

Procedure

Your entry point is PATCH /things/{thingId}.

Authenticate

In order to use the Things HTTP API, you will need to authenticate. In this example we authenticate with a bearer token, using the client created in Provisioning via Device Provisioning API.

images/confluence/download/attachments/1647785660/things-auth.png

Close the pop-up.


Patch the hello world thing


This request simulates how your business application (or your device) might change the feature.

  • Navigate to Things > PATCH /things/{thingId}.

  • Click Try it out.

  • Set the thingId - in our example example.dm:hello-world-device-01.

  • Set the Request body - in our example we add an attribute "manufacturingYear", and a "lamp" feature

    {
    "attributes": {
    "manufacturingYear": "2021"
    },
    "features": {
    "lamp": {
    "properties": {
    "configuration": {
    "isON": true,
    "string": "supports only on/off no color settings"
    }
    }
    }
    }
    }

  • Click Execute.

Result

The response is 204, meaning the thing was successfully patched (merged).

Check your work

You can either use the Bosch IoT Suite Console to see if the new attribute is changed, or you can request again all attributes using the HTTP API.

A GET thing request would respond with the complete thing structure.

{
"thingId": "example.dm:hello-world-device-01",
"policyId": "example.dm:hello-world-device-01",
"attributes": {
"manufacturingYear": "2021",
"Info": {
"displayName": "",
"gateway": false
},
"manufacturer": {
"name": "ACME demo corp.",
"location": "Berlin",
"serialno": "4200",
"model": "fancy"
}
},
"features": {
"temperature": {
"properties": {
"status": {
"value": {
"currentMeasured": 42,
"minMeasured": 0,
"maxMeasured": 0
}
}
}
},
"lamp": {
"properties": {
"configuration": {
"isON": true,
"string": "supports only on/off no color settings"
}
}
}
}
}