uriVariables needs to be more limited

[sebastiankb]

uriVariables should only typed with simple data types such as string and number. Complex types like arrays and object should not allowed. We need an assertion about this.

[relu91]

Another thing that is confusing about uriVariables is the ability to use them also in action affordances. There, we have already the input field which specifies the required arguments of an action. I think we should rather rely on the input field and specify that the URI template can refer to first-level properties in the input data schema. For example, consider this odd Web Thing that has an action that takes in input id as URI variable and a payload:

"configure":{
            "title": "configure",
            "description": "",
            "input": {
                "title": "payload",
                "type": "object",
                "properties": {
                    /**/
                }
            },
            "uriVariables": {
                "id":{
                    "type": "string"
                }
            },
            "output": {},
            "forms": [{
                "href": "http://example.com/subdevice{?id}"
            }]
        }

Essentially we could simplify the affordance like this:

"configure":{
            "title": "configure",
            "description": "",
            "input": {
                "title": "payload",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    }
                    /**/
                }
            },
            "output": {},
            "forms": [{
                "href": "http://example.com/subdevice{?id}"
            }]
        }

A runtime just needs to know which property of the input should be inserted in the URI. Conflicts between the payload and the URI template can be easily resolved by using a different name.

Regarding other interaction affordances (i.e., properties and events), having uriVariables it's a strong hint for a bad design choice as they are probably actions. I've not found anything on the document describing this possible issue. I think we should consider also this problem when talking about #1020.

[egekorkan]

Regarding other interaction affordances (i.e., properties and events), having uriVariables it's a strong hint for a bad design choice as they are probably actions.

The main use case I find for uriVariables in properties or events is to filter a key of an object, give an input for getting something or to simply describe already existing Web APIs. I think that the first two points are not really RESTful designs but they are what literally every weather API does... Examples of weather APIs below:

• https://openweathermap.org/current
• https://www.weatherbit.io/api/weather-current
• https://developer.accuweather.com/accuweather-forecast-api/apis : This one is actually not uriVariables but uriTemplates that we cannot describe yet in TDs, I think?

[relu91]

Yes! exactly. What I would like to see on the document is an explainer saying that: "retrofitting an existing API might need the usage of uriVariables as in (examples of APIs that needs uriVariables) .... however they SHOULD not be used when designing a new WoT system.

Edit:
Just wondering, looking at the APIs, what does stop you to create an Action called retriveCurrentWeather? (of course, if we'll define a mapping between input and the URI parameters, as explained above).

[egekorkan]

@relu91 I think your second example above has some copy-paste artifact left in there. I guess uriVariables in the second example should not be there?

Regarding modeling it as an action, I think that it does not make sense from an interaction modeling point of view. Here, a data is simply being retrieved and retrieving it does not cause any changes in the system. I think the 3rd option used by Accuweather is the most logical one and uses REST principles better.

[relu91]

@relu91 I think your second example above has some copy-paste artifact left in there. I guess uriVariables in the second example should not be there?

Nice catch! updated.

Regarding modeling it as an action, I think that it does not make sense from an interaction modeling point of view. Here, a data is simply being retrieved and retrieving it does not cause any changes in the system. I think the 3rd option used by Accuweather is the most logical one and uses REST principles better.

Yes, I agree Accuweather seems more reasonable from a REST point of view and that's maybe why we should keep uriVariables around.

Regarding the fact that action must change something in the system, I think it from the earlier definition of a Web Thing. Reading from the architecture a Web Thing can now be an virtual entity and a action has less strict definition:

An Action is an Interaction Affordance that allows invoking a function of the Thing. An Action MAY manipulate a state that is not directly exposed (cf. Properties), manipulate multiple Properties at a time, or manipulate Properties based on internal logic (e.g., toggle). Invoking an Action MAY also triggers a process on the Thing that manipulates state (including physical state through actuators) over time.

As I interpret it, it seems that I am also allowed to think of actions as processes or logical operations that a Thing can do. In our experiments, we usually follow the OOP rule of thumb, so if I property getter needs inputs then it's actually an action. Furthermore, if something is logically a long-running process then starts when invoked and can be named as a verb then it's an action. For example, a performSelfCheck that computes the sanity of the configuration of a web thing is an Action.

Back to the API that you posted, I know that here we are really talking about details but taking as an example openweather you might even think it as if there's a collection of weather forecasts and you are selecting the city. Consequently, it could be seen as if you are filtreing / processing it to retrive the requested information -> an Action.

[egekorkan]

In the call of 12.05, we have decided to close this issue but open a new one at: #1138