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.

The x-things-parameter-order header has been introduced for messages (e.g. operation request to a gateway or device).
See 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 
}

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.

In case your business application uses our things-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.

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

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.