Define error responses

[mmccool]

For error response, having an array so we can define error responses would be quite useful. Use case supporting w3c/wot-thing-description#617

[farshidtz]

Not just errors, but also for various success responses with corresponding status codes, content types, and headers.

E.g. for PUTing TD:

{
    "href": "/td/{id}",
    "htv:methodName": "PUT",
    "contentType": "application/td+json",
    "response": [
        {
            "description": "Created new resource",
            "htv:statusCodeValue": 201
        },
        {
            "description": "Updated existing resource",
            "htv:statusCodeValue": 204
        },
        {
            "description": "Invalid input",
            "htv:statusCodeValue": 400,
            "contentType": "application/json"
        },
        {
            "description": "No authentication",
            "htv:statusCodeValue": 401,
            "contentType": "application/json"
        },
        {
            "description": "Insufficient rights",
            "htv:statusCodeValue": 403,
            "contentType": "application/json"
        }
    ]
}

More examples are provided as comments.

[egekorkan]

Also related to w3c/wot-scripting-api#200

I think that the whole working group needs to define error types that are WoT-specific but at the same time mappeable to protocol errors/status codes.

[benfrancis]

I definitely agree this is needed and in the case of the directory API these error conditions can be documented in the API specification so that clients know what the different errors mean.

If this syntax was generalised to all Thing Descriptions I'm not sure how clients would automatically assign meaning to arbitrary response codes and human-readable descriptions and distinguish between success and error conditions in different protocols. As @egekorkan says it may be necessary to define WoT-specific error codes which can then be mapped onto different underlying protocols.

[farshidtz]

Discussed in w3c/wot-thing-description#617 and added to TD 1.1.