Examples for actions using URI variables should explain why not using input

[zolkis]

In Example 21 for instance, it should be explained why uriVariables have to be used instead of the input property of the ActionAffordance, which has qualifiers like idempotent which are not possible with uriVariables.

In general, the necessity and use of uriVariables is still not well explained in the TD spec.

For instance, they act as a way to convey parameters to all interactions.

From there, a Property affordance is like an action, since it takes URI variables (defined by DataSchema). So we have inputs in form of uriVariables and output in form of the Property affordance itself since it extends DataSchema.

I find this very messy. It would be more clear if at InteractionAffordance level we'd have the output property, also for Properties and Events.

Then for Actions, we don't really need input once we have uriVariables. There is no good explanation in the TD spec why both are needed. Or we need a way to say inputs become uriVariables in the bindings.

If both are to be kept, they must be properly explained, with use cases and examples.

[egekorkan]

I agree with the lack of explanation. I can tell from my experience is that uriVariables are generally used with an HTTP GET request in order to send data. So in the TD case, if there is an interaction that is physically an action (like brewing a coffee) but the implementation is programmed with an HTTP GET + uriVariables, we have to use the uriVariables.

It also makes more sense in properties when the Consumer can do filtering on an Object. @fatadel did it for the node-wot tutorial at http://www.thingweb.io/smart-coffee-machine.html . Search for the line We also want to override write and read handlers for availableResourceLevel property, since we need to utilize uriVariables. for the exact point on this.

[zolkis]

Actually it was more useful to look at the code: https://github.com/eclipse/thingweb.node-wot/blob/master/packages/examples/src/scripts/coffee-machine.ts

There you can see the same point I raised: it is using uriVariables here instead of input, AFAICT for no good reason, whereas here it is using input.

I understand uriVariables are used for relatively good reason here because it defines an object Property whose members can be queried separately using uriVariables.

However I would argue the use case could be also solved without uriVariables by defining an Action+input in order to get the individual values instead of Property + uriVariables, which again proves my point: IMHO modeling availableResourceLevel with a property is a broken solution IMHO, made possible by exposing uriVariables.

IMHO uriVariables should be only a means to transport input parameters and should be encapsulated by the bindings. So far I have not seen a single use case with them that could not be solved better by using the standard interaction affordances. That does not mean these use cases don't exist, and actually I wish to be educated on good ones, please :).

[danielpeintner]

In Example 21 for instance, it should be explained why uriVariables have to be used instead of the input property of the ActionAffordance, which has qualifiers like idempotent which are not possible with uriVariables.

In my opinion the only reason for having uriVariables is to describe existing services. There is is no doubt that URI variables are in use on the Web.

If I read your argument correctly, you are saying that on the TD level it should not be any difference between uriVariables input vs. any other input. The binding should build the according request whether with uriVariables or the information in the body. Correct?

[takuki]

As a note, this issue is closely related to #569 .

In my opinion the only reason for having uriVariables is to describe existing services. There is is no doubt that URI variables are in use on the Web.

Is it possible to achieve both to describe existing services and encapsulate uriVariables in Binding Templates at the same time?

[takuki]

In 2020-06-12 telecon, @egekorkan volunteered to make a PR with @danielpeintner 's openweathermap example: https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=439d4b804bc8187953eb36d2a8c26a02

@zolkis is going to create another issue with regards to multiple inputs to action from Scripting API's aspect. There is something that needs to be clarified in TD.

[egekorkan]

I think that this is properly described now with a note that says that this should be done only for retrofitting when needed