Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Error conditions for form requests #303

Closed
benfrancis opened this issue Nov 23, 2018 · 21 comments
Closed

Error conditions for form requests #303

benfrancis opened this issue Nov 23, 2018 · 21 comments
Labels
Forms Topics related to the forms container Propose closing Problem will be closed shortly if there is no veto.

Comments

@benfrancis
Copy link
Member

benfrancis commented Nov 23, 2018

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
Copy link
Member

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
Copy link

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

@mlagally
Copy link
Contributor

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
Copy link
Member

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
Copy link
Contributor

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
Copy link
Member

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

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

@sebastiankb sebastiankb added the Needs discussion more discussion is needed before getting to a solution label Feb 25, 2019
@sebastiankb
Copy link
Contributor

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

@sebastiankb sebastiankb added Defer to next TD spec version This topic is not covered in this charter, maybe included for the next TD version. and removed Needs discussion more discussion is needed before getting to a solution labels Mar 1, 2019
@sebastiankb sebastiankb added the Forms Topics related to the forms container label Jan 23, 2020
@egekorkan
Copy link
Contributor

Relevant issue in Scripting API: w3c/wot-scripting-api#200

@sebastiankb
Copy link
Contributor

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.

@sebastiankb sebastiankb removed the Defer to next TD spec version This topic is not covered in this charter, maybe included for the next TD version. label Dec 9, 2020
@egekorkan
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

There are some in the above linked issue

w3c/wot-scripting-api#200 (comment)

@egekorkan
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

@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
Copy link
Member Author

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
Copy link
Contributor

sebastiankb commented Dec 17, 2020

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
Copy link
Contributor

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

@sebastiankb sebastiankb added the Propose closing Problem will be closed shortly if there is no veto. label Mar 25, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Forms Topics related to the forms container Propose closing Problem will be closed shortly if there is no veto.
Projects
None yet
Development

No branches or pull requests

6 participants