Support for additionalResponses

[relu91]

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]

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

[lu-zero]

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

[zolkis]

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]

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]

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

[relu91]

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]

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).