w3c/wot-scripting-api

Support for `additionalResponses`

relu91 opened this issue · 9 comments

relu91 commented

Current TD specification introduced the concept of additionalResponses to model APIs that might return different payloads from the same affordance. The field is used also to model both successful responses and error responses. For example, the Thing Description of a Thing Description Directory contains the following:

"actions": {
        "createThing": {
            "description": "Create a Thing Description",
            "uriVariables": {
                "id": {
                    "@type": "ThingID",
                    "title": "Thing Description ID",
                    "type": "string",
                    "format": "iri-reference"
                }
            },
            "input": {
                "description": "The schema is implied by the content type",
                "type": "object"
            },
            "forms": [
                {
                    "href": "/things/{id}",
                    "htv:methodName": "PUT",
                    "contentType": "application/td+json",
                    "response": {
                        "description": "Success response",
                        "htv:statusCodeValue": 201
                    },
                    "additionalResponses": [
                        {
                            "description": "Invalid serialization or TD",
                            "contentType": "application/problem+json",
                            "htv:statusCodeValue": 400
                        }
                    ]
                }
            ]
        },
relu91 commented

Notice that there is also the concept of response that we currently don't take into account.

lu-zero commented

And it has to be composed with Action::output (and the same logical concepts in Property and Event).

  • 👍1
zolkis commented

In the context of a scripting API these are errors - which we do take into account, but we may want to extend the details.
Implementations can choose to report these.

relu91 commented

In the context of a scripting API these are errors - which we do take into account, but we may want to extend the details.
Implementations can choose to report these.

Not all of them, since you can express alternative success responses too.

zolkis commented

Doesn't matter, the API is still fine with a Promise... eventually you can resolve it with an object.

relu91 commented

Call 13/05:

  • We need to handle the use case and give an example or a note. Eventually, an algorithm is needed.
  • @danielpeintner Since actions have output schema what happens when the additionalResposes have another schema? @relu91 is a grey area we need to understand how to explain the issue.
  • @JKRhb can we generalize it with other protocols?
  • @zolkis This is an example of why the scripting API is useful. Best to solve in the binding.

We need somebody who can work on this issue and propose pointers to a solution.

lu-zero commented

We have a normal path that is relying on the logical data schemas of the affordance and we have a richer path that adds additional schemas bound to the form (and thus potentially protocol specific).

As it is the best we can provide is the data and the schema it matches, if one is matched.

We should discuss on TD if we want to say anything regarding when more than a dataschema matches probably. For TD 2.0 could be useful to give provisions to map protocol-specific errors and/or other side-channel metadata to logical concepts so would be possible easier to have protocol-translating proxies (e.g http 404 -> not_found).

relu91 commented

Call 05/08:

relu91 commented

@danielpeintner we can have an umbrella issue and split the work about handling successful and error responses. @relu91 will do this.

I've updated the first post with the links to the two newly created issues.

  • 👍1