-
Notifications
You must be signed in to change notification settings - Fork 63
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
clarify semantics of actions #213
Comments
we need some concrete examples for the error handling. |
One example is where there is an "internal error" when executing the action. In the Arena Web Hub, this is signalled with a 5xx status code when using either HTTP or WebSockets for the protocol, and reported to clients via the Scripting API by rejecting the promise for the action along with a suitable error message. Another example of an error is a timeout when the promise is left hanging for an excess amount of time. In Arena, this too is signalled by rejecting the promise. I would advise against baking complex semantics into the TD spec as it is better handled at the application layer. The core abstract API should remain as simple as possible. I know that there are use cases where it is appropriate to have actions that can be cancelled, and use cases that require progress indicators. However, I consider these both to be application level requirements that can be implemented on top of the core notion of asynchronous actions with inputs and outputs. For instance, if an action is cancellable it could output a reference to an ongoing process. Another action can then be used to cancel the process by passing the process ID. Progress for some extended process could be signalled via a sequence of events. @mlagally can you explain why you are asking for synchronous actions, given the web of things generally speaking involves action at a distance, making the abstract model for actions to be asynchronous/. |
@draggett Sorry for my late response. WoT is defining a generic interface description language (like CORBA did many years ago) that provides an abstraction from devices via properties, actions and events. See for example the "action" on the Oracle IoT Cloud Service: https://docs.oracle.com/en/cloud/paas/iot-cloud/iotrq/op-iot-api-v2-apps-app-id-devices-device-id-devicemodels-devicemodel-id-actions-action-name-post.html, which returns a status code and a URL for this purpose.
The current specification can describe both synchronous and asynchronous ways of using the API, and probably it does not even have to be more specific. However I think we should extend the current action definition in the TD spec with an additional "response code" and ideally a "response message", which corresponds to the status code in HTTP or a return code of a function call. |
Mozilla has the same use case of action requests which create a new resource that can be polled for action status or cancelled. e.g. Request:
Response:
I've not been able to figure out how to describe this with the current Thing Description specification, see #302 |
@mlagally wrote:
and
Do we really need to standardise that? I suspect not as different contexts will involve different categories of responses. You are free to declare an action that returns an object with a numeric code together with a enum, string or JSOB object if that's what your application needs. Some errors will be handled through the platform API, e.g. in Arena, actions return a Promise which is rejected when the server reports an internal error, there is a time out, or when the server rejects the security token passed with the request. |
@benfrancis wrote
You can model that as an action response, but then need to model how you deal with it. One idea is to model the fade process as a thing it its own right. Another is to return an ID that you can listen for using a status event that contains the ID. A further idea is to declare another action for acting on long lasting processes. I recommend that we keep the core interaction model simple and allow applications to layer more complex interaction patterns on top, perhaps using libraries to simplify this. Otherwise we risk over complicating the Web of Things as more and more people come to us with their own interaction patterns demanding that the TD spec is updated to match. |
@draggett wrote:
I guess we can get away by adding a response code and a response message to the output data schema, however this is completely up to the implementer. |
same situation as discussed here #303 This topic can be covered in a successor version of the TD. |
we will discuss this in today's TD call. Also see #890 |
close this issue since TD now has |
The spec should clarify the semantics of synchronous and asynchronous actions:
How can an asynchronous be monitored? How are execution failures (exceptions) communicated?
The text was updated successfully, but these errors were encountered: