Clarifying how readmultipleproperties work

[egekorkan]

The TD spec is not clear on how to implement readmultipleproperties from the Consumer side. The corresponding paragraph is:

If not specified otherwise (e.g., through a TD Context Extension), the request data of the readmultipleproperties operation is an Array that contains the intended PropertyAffordances instance names, which is serialized to the content type specified by the Form instance.

The words request data exist only here in the document which is not clear where this array should be in the request. This op value raises another concern since in protocols like HTTP and CoAP it is not a good practice to send a body/payload with a GET request if this is what is hoped for. In MQTT it would not be possible at all as far as I know.

I am guessing that request data was written explicitly and it would be the job of protocol bindings document to explain how to incorporate it?

[sebastiankb]

request data = response payload

[egekorkan]

But request payload means body for the HTTP request which would then conflict with the default assumption of using the GET method which is recommended to not have a body. Maybe it is even better to leave it not defined since it would differ for protocols?

[sebastiankb]

well it is not the best practice, however, http spec does not forbid using body on a GET

https://tools.ietf.org/html/rfc7231#section-4.3.1

In MQTT it would not be possible at all as far as I know.

I would expect that there will be separate topic defined where you can provide the desired properties.

[egekorkan]

Ok, in this case, I would propose to close this issue and keep it not exactly specified since it would depend on protocols and the binding templates document can explain how it would work for different protocols.

[takuki]

In 2020-02-28 TD call, it was suggested to keep this issue open till we have a consensus on how to properly implement this feature.

[zolkis]

Do have enumerable concrete use cases for the feature?, or just filling a theoretical gap?
If we have these use cases, we should already know the feasibility and how to do it.
If we don't, IMHO we better remove it until we figure out how can it work transparently over multiple protocols.

Is there guaranteed semantics, like is readmultipleproperties supposed to always fetch multiple Properties with a single request? Or can implementations simulate it by issuing subsequent requests? (in which case it doesn't make any sense to have it).

Apps would not lose much since they still have the readproperty and readallproperty ops, where a Property can be a compound structure (array or object). So all properties desired to be fetched with a single request could be encapsulated by an object or array of Properties. This pattern can also encapsulate whether the server supports transactions.

[egekorkan]

One way to do readmultipleproperties would be if a Thing level form has "op":"readmultipleproperties" (so only readmultipleproperties) and somehow describes that the response will contain properties 1, 3 and 5. This is of course not as specified by the specification, i.e. the Consumer doesn't have the option to choose the desired properties with an Array.

Do have enumerable concrete use cases for the feature?, or just filling a theoretical gap?

There was a mention in the call of 28/2 that Mozilla had this implemented but I couldn't find it in their documentation. @benfrancis do you have an opinion?

[egekorkan]

There is also a problem if Thing wants the Consumer to provide a list of property names in uriVariables. For example, the request needed is the following:

HTTP GET to http://example.com/?props=property1,property2

which returns the values of property1 and property2.

I would expect that the Thing level form would be something like:

    "forms": [{
        "op": "readmultipleproperties",
        "href": "http://example.com/{?props}",
        "contentType": "application/json",
        "htv:methodName": "GET"
    }]

How can we specify that the values of props should be property names? Do we need uriVariables in the Thing level? Even then, would the following be understood as a list of property names by every implementation?:

"uriVariables": {
  "props": { 
    "type": "array",
    "items":{
      "type":"string",
      "@type":"properties"//this is not the correct one but something similar
      }
  }
}

[egekorkan]

Yet another aspect to think about:
Does the Consumer have to provide a list of properties or could it be that that form returns a constant subset of the properties without any input? For example, a TD has property1, property2 and property3 where the response of a form like the following contains the values of property1 and property2:

{
// ...
"forms":[
  {
    "href":"http://example.org/myfavouriteproperties",
    "op":"readmultipleproperties",
    "contentType":"application/json",
    "htv:methodName":"GET",
    "description":"returns property 1 and 2"
  }
]
// ...
}

Also, this would raise an issue on how the Consumer would know that only property 1 and 2 would be returned.