Wot-thing-description: Error conditions for form requests

[benfrancis]

How should a Thing Description define error conditions for form requests? How does a client know what different success and failure responses are possible to a given form request and what they mean?

[draggett]

Good question, for Arena, I followed the HTTP status codes and also re-used these for my WebSockets subprotocol. I am unsure what status code to use for situations such as when the security token has expired. At the application level, a developer may want to message the owner to ask him/her to login and refresh the token. I am working on an example for how to do this via an SMS request to the phone number provided when the owner created an account on the web hub.

[handrews]

It would be nice to use RFC 7807 if additional detail beyond status codes is desired.

[mlagally]

There was a similar discussion in one of the recent TD calls wrt. to action semantics. The challenge is to define a mechanism that abstracts from HTTP and also works for other protocols.

[draggett]

We certainly need to address the request/response pattern where the response may signal that the request couldn't be dealt with for some reason. This could include timeouts where the client generates a response when the server fails to respond within a reasonable time.

[sebastiankb]

I'm not sure, but it seems to me to be more of an API topic, not a TD one. E.g., try-catch statements can give you some hints from your used protocol bindings such as 400 and 401 number codes for http. The kind of errors can be infinity and depends on the behavior of client's implementation (e.g., retry, retry with timeout, user notification, etc.)

[draggett]

Whilst we can go into concrete details at the API specification level, TD as a declaration of an abstract interaction model for things, should include normative constraints on interactions that abstract away from the details of a particular API.

However, getting back to Ben's question, how can one design a client platform without knowing about the error codes that a given server may provide for a specific protocol?

[sebastiankb]

I'm still trying to figure out what the TD is supposed to offer here in particular. Concrete use case and proposals for the TD would be helpful.

[mlagally]

Whilst we can go into concrete details at the API specification level, TD as a declaration of an abstract interaction model for things, should include normative constraints on interactions that abstract away from the details of a particular API.

However, getting back to Ben's question, how can one design a client platform without knowing about the error codes that a given server may provide for a specific protocol?

There are use cases, where it is sufficient for the client to know if an action was successful or failed via a simple status code (e.g. a boolean in the simplest , or just a few values e.g. corresponding to the first digit of a HTTP response code) and to present a string message (e.g. like an exception message in Java) to the user.
For HTTP this message could contain a combination of the error code and message, e.g. "500 internal server error", for other protocols appropriate message content could be delivered by the protocol implementation.

[sebastiankb]

@mlagally How should this runtime information be reflected in the TD?

[sebastiankb]

since there is no concrete proposal yet, I will mark this as a possible topic for a future version of the TD.

[egekorkan]

Relevant issue in Scripting API: https://github.com/w3c/wot-scripting-api/issues/200

[sebastiankb]

Again, I have the impression that this topic has more to do with a certain sub-protocol with a certain payload pattern that allows to carry error messages.

In today's TD call we should decide how relevant this topic is and whether it should be covered in TD 1.1.

[egekorkan]

So from the discussions in Scripting, it is not related to a protocol but basically how can one understand error message like one understands payloads in a non content type based way (JSON Schema).

[sebastiankb]

So from the discussions in Scripting, it is not related to a protocol but basically how can one understand error message like one understands payloads in a non content type based way (JSON Schema).

I'm not sure I understand. Can you give an example.

[egekorkan]

There are some in the above linked issue

https://github.com/w3c/wot-scripting-api/issues/200#issuecomment-590268621

[egekorkan]

But I think this issue is more relevant to binding templates. What is meant is that there can be different status codes for the responses and how should they be handled. Maybe like in OpenAPI https://swagger.io/specification/ (you need to manually scroll down to Paths Object example

[sebastiankb]

From today's TD all:

• we were discussion some ideas how this can be solved
• here would be a first proposal (see the error term in forms)
• @benfrancis is this something the direction you have in mind? Otherwise can you share a concrete example how this would look like what you think about.
• @mlagally can you also have a look on that

[benfrancis]

@benfrancis is this something the direction you have in mind? Otherwise can you share a concrete example how this would look like what you think about.

The original reason for me filing this issue was in response to a request to give examples of the kinds of features of Mozilla's Web Thing API which could not be expressed in a W3C Thing Description. In this case that was defining the meaning of different possible error responses to a given request in a given protocol. Therefore I didn't really have a solution in mind because Mozilla's solution was to define the API in a separate specification rather than declaratively in a Thing Description.

However, if the Thing Description was to cover this use case then my instinct would be to look at what Open API does as a starting point as @egekorkan suggested.

I didn't really understand the linked example as it just seems to define an error to have the same data schema as the payload needed to set a property and I don't recognise the "schema" keyword for a Thing Description.

I note that OpenAPI has a feature to define multiple possible responses to a given request, indexed by their HTTP status code. Each response type can have one or more content types, a schema to describe the format of its payload and a human-readable description which explains what the response means.

So thinking off the top of my head, one solution could be to build on the current response member of a form with a responses member which provides a map indexed on response status code, e.g.

{
    ...
    "properties": {
        "level": {
            ...
            "forms": [{
                "href": "http://mything.com/properties/level",
                "op": ["writeproperty"],
                "responses": {
                    "200": {
                        "type": "number",
                        "description": "Successfully set level property"
                    },
                    "400": {
                        "description": "Failed to set level property"
                    },
                    "401": {
                        "description": "Not authorised to set level property"
                    }
            }]
        }
    },
    ...
}

This could work for HTTP, but I've no idea how you'd scale it to work with any protocol.

[benfrancis]

Actually, I note there is already a proposal for multiple responses including error codes, which has also recently surfaced as a requirement in the discovery task force.

My preference would be that response can either be an ExpectedResponse object or an array (despite the backwards compatibility issues), but there is arguably already precendent set with title/titles and description/descriptions.

[sebastiankb]

I like the mentioned proposal since it is more protocol independent. A way to be backwards compatible can be:

      "forms": [
        {
          "op": ["writeproperty","readproperty"],
          "href": "/resources/{id}",
          "response": {
              "contentType": "application/json",
              "statusCodes" : [
                {
                "description": "Success response",
                "htv:statusCodeValue": 200
                },
                {
                "description": "Resource not found",
                "htv:statusCodeValue": 404
                }
            ]
          }
        }
      ]

The name statusCodes can be also more generic.

Downside: we would introduce another level of definition

[sebastiankb]

Propose closing. Issue is addressed by the new AdditionalExpectedResponse. Latest discussion can be found here.