search

WebThingsIO / api

Web Thing API Specification
http://iot.mozilla.org/wot/
Other
164 stars 25 forks source link

Allow data member in action responses #107

Open mrstegeman opened 5 years ago

mrstegeman commented 5 years ago

Actions may need to return data of some sort, so a data member should be allowed.

benfrancis commented 5 years ago

This will require adding an output member to the Action object in the Thing Description, in addition to the input member, to tell the client what output to expect from an action.

This is something which is supported in the latest W3C draft, but which we haven't yet included in our draft mainly to a lack of use cases. Have you come across some examples where an action returns an output? (I'm sure there must be many).

RoboPhred commented 4 years ago

I would like to use this with building an entirely self-describing thing management api for my zwave gateway implementation. I am trying to avoid any management specific API endpoints and describe every management activity in terms of things, properties, and actions.

Many use cases come up when exposing Things that represent management concerns, as most management activities will create Things, either real or virtual. Some examples are creating scenes, adding devices, and creating schedules.

For example, I would like to have a "Scheduler" thing with a "Create new schedule" action. Triggering this action should create a new virtual "Schedule" thing, and I would like the action to return the Thing ID of the newly created Scene thing so the frontend can redirect to it. Ideally, the workflow would create the Schedule Thing, the user would be redirected to the new thing, and the user would then use actions on the Schedule to add things.

mrstegeman commented 4 years ago

The W3C spec now has an output member for an action.

The gateway, the add-on bindings, and the webthing libraries will all need to be updated to support this, though.

RoboPhred commented 4 years ago

How closely is the Mozilla WOT standard attempting to follow the W3C standard though? Mozilla WOT has the concept of ActionRequests, while W3C provides no affoardance for historical action data.

Presumably, W3C expects the output to come back in the response to the action invocation. How does the output fit in with the Mozilla WOT's ActionRequests?

mrstegeman commented 4 years ago

@benfrancis can probably give more detail, but this is one of the biggest divergences between the two specs which is still unresolved.

benfrancis commented 4 years ago

The W3C specification doesn't define how action requests actually work, as that's meant to be defined declaratively in the form of the Action. The default method for invoking an action in the HTTP protocol binding is to send a POST request, but the specification doesn't define what should happen when the action request succeeds or fails.

It could be assumed that the result is communicated in the response to the HTTP POST request, in the format defined in the output member, but that would only work if the duration of the action is short enough to complete by the time the HTTP request times out, and is not really how POST requests are meant to work. This is why the Mozilla specification uses the concept of an action queue with ActionRequest resources, which allows for long-running actions like opening or closing a blind which may take longer than the duration of an HTTP request timeout.

This can not currently be expressed in a W3C Thing Description and there's an open issue for that on the W3C specification which is being discussed for the next version of the specification.