Message payload need to follow a specific

The digital twin layer supports a header named x-things-parameter-order.
The x-things-parameter-order header has been introduced for messages, e.g. operation request to a gateway or a device.

Example: A user sets a RGB based color via UI. The correct order is provided via the value of such a header, in our example: [“red”,“green”,“blue”].
Thus, the request body can be set in JSON notation, and the intended order of the structure is kept within the header. Only top-level keys are added to the array.

Header

x-things-parameter-order:["red","green","blue"]

Payload

{
"red": 255,
"green": 255,
"blue": 0
}

Table of contents:

Custom client

In case your business application uses a custom client to compose the message, you will need to specify both, the header with the order, and the message composed in the correct order.

cURL example

curl -X POST \
https://things.eu-1.bosch-iot-suite.com/api/2/things/{thingId}/features/{featureId}/inbox/messages/{messageSubject} \
-H 'Content-Type: application/json' \
-H 'x-things-parameter-order: ' \
-d '{
"red": 100,
"green": 200,
"blue": 150
}'

Result

x-things-parameter-order:["red","green","blue"] - header needs to be additionally generated by your business application.

Ditto client

In case your business application uses the ditto-client to compose the message, you will only need to take care the message is composed in the correct order (i.e. the order your firmware or gateway adapter would expect it).

Java example

final JsonObject jsonObject = JsonObject.newBuilder()
.set("red", 50)
.set("green", 150)
.set("blue", 250)
.build();
 
client.live().forId(toThingId)
.message()
.from()
.subject("switchColor")
.payload(jsonObject)
.contentType("application/json")
.send();

In such a case, the Things service will internally set the respective header and value with the exact order as given in your code.

Things service will not set the header x-things-parameter-order if the message payload is an array, a primitive value, or null.

Result

x-things-parameter-order:["red","green","blue"] - header is generated by the Things service.

HTTP API docs

In our HTTP API docs, there is no such header specified. Thus, the Things service will rely that the payload you put there is the correct order.

Request

POST /things/{thingId}/features/{featureId}/inbox/messages/{messageSubject}

Content-Type: application/json

Request body:

{
"red": 255,
"green": 255,
"blue": 0
}

Result

x-things-parameter-order: ["red","green","blue"] - header is generated by Bosch IoT Things.