How to make sure my message payload follows a specific order?
I have noticed, that the Things service is introducing a header named x-things-parameter-order. However, it is not clear who is in charge to set the header.
Answer
The x-things-parameter-order
header has been introduced for messages (e.g. operation request to a gateway or device).
See Protocol specification > Custom message headers.
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
}
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 the Things service.