Abstract vs. Concrete Protocol Bindings

[benfrancis]

[Edit: Example of the kinds of issues a concrete protocol binding might address]

Option 1

There is a single action queue for a Thing defined in the links member of the Thing Description:

"links": {
   "actions": "/things/pi/actions"
}

Action requests are posted to the actions resource which is a queue of all action requests on the Thing:

/things/pi/actions/123e4567-e89b-12d3-a456-426655

Option 2

Each action has its own URL, defined in the actions member of the thing description:

  "actions": {
    "reboot": {
      "name": "Reboot",
      "description": "Reboot the device"
      "href": "/things/pi/actions/reboot"
    }

Each action resource is a queue of action requests which you POST requests to:
/things/pi/actions/reboot/123e4567-e89b-12d3-a456-426655

We could try implementing both, but then the URL namespaces used above would conflict.

[mkovatsc]

Much of this is implementation detail that should not be standardized. It must be up to the Servients/Things/gateways how they implement their queue, if they expose it, and where they would expose it. To figure out the latter, we need implementation experience, so don't get this as pushback on the activity itself; it might fit better in the IG and only have the standardization requirements here in this issue tracker.

What should be standardized is the metadata for it, such as maybe a link relation type for the top-level links element that points to a collection resource, or maybe rather a semantic type for a Property that represents the queue. The latter would avoid side-channeling the queue information.

BTW: We have a use case for doing something similar for open Events, e.g., alerts that have not been confirmed yet. (This includes further a requirement for interacting with events...)

[benfrancis]

Hah, sorry, I actually posted this issue in the wrong GitHub repo by mistake while posting a list of issues on Mozilla's implementation (sorry, it's been a long day), but I'm actually kind of pleased that I did.

This is a good example of abstract protocol bindings (as you described) vs. concrete protocol bindings (as I described above).

If the binding is defined entirely by the Thing Description, how would you give the client enough information to know how to request an action? It would need to know:

• The URL to use
• The protocol to use
• The method to use (if the protocol has methods)
• The syntax of the data to send
• The syntax of the data it would get back
• What messages indicate success
• What messages indicate errors and what they mean
• How to cancel an action request
• How the get the action's status
• How to know when the action is completed
• How to get a list of action requests

Alternatively all of this could be specified by a concrete HTTP binding specification like the one this issue was actually meant to be about https://iot.mozilla.org/wot/#actions-resource

(Feel free to re-file or re-name this issue accordingly).

[benfrancis]

And what does the client do if it doesn't support the protocol available?

[mkovatsc]

Hah, sorry, I actually posted this issue in the wrong GitHub repo by mistake while posting a list of issues on Mozilla's implementation (sorry, it's been a long day), but I'm actually kind of pleased that I did.

No worries, discussing more on the technical level is good (and is why would like to see Mozilla actively participating in the PlugFests).

• The URL to use

href in the Interaction (check)

• The protocol to use

URI scheme (check)

BTW @benfrancis : This should help your concerns, as it already limits the candidates of protocols that can be used as protocol binding: they need a registered URI scheme. When specifying a URI scheme for more IoT protocols, we could try to force in some specification of how interactions should work in regard to links and forms (please see #108 (comment) on this as well); might be doable through the role of the IETF IoT Directorate to provide reviews in the RFC process (@akeranen thoughts?).

• The method to use (if the protocol has methods)

Default from model or forms metadata (check)

• The syntax of the data to send
• The syntax of the data it would get back

Concrete Media Types or generic Media Types + schemas (check)

• What messages indicate success
• What messages indicate errors and what they mean

Protocols must be able to indicate this and, in the end, it is basically mapped to a resolve() or a reject() in the code, where the meaning of errors results in a more precise error thrown and more appropriately being handled. (check)

The better protocols are at this, the more likely they survive in the wild. If there is a protocol that does not have a generic error mechanism, it is not a good fit and no sane developer should use it (looking at you, MQTT for anything other than moving telemetry data in one direction...).

RESTful protocols with a hierarchy of errors are a very good fit in my opinion: they give you the basic resolve() or reject() indication (success or error), but in the case of an error the client gets more and more hints how to recover: client or server error, error details (e.g., not found or not authorized), and eventually an error response body that can range from a diagnostic message (cf. CoAP) to hypermedia controls on how to recover automatically.

• How to get a list of action requests

Can be modeled as a Property. (check)

If Properties, Actions, and Events are not good enough for modeling something like this, how would they be good enough to model your actual application?

• How to cancel an action request
• How the get the action's status
• How to know when the action is completed

This is where we leave the descriptive approach of WoT, which is good, because here WoT can actually innovate and complement existing standards! Please correct me, but to my knowledge most existing IoT platforms and standards lack a good, common design pattern here. My immediate goal would be to have the right extension point for this in the TD spec and get working on standardizing this in the next charter period. We cannot shove everything through the door at once... (todo)

The concept to handle this is based on hypermedia controls (see e.g., #108 (comment)) and was already tested in prototypes around 2016. I see invoked Actions to be similar to Things: they have Properties for the status (including completion) and Actions such as cancel. So why not reuse the Interaction model from the TD for this? We have some implementations that use "transient Things" for this, i.e., short-lived Things that pop up and go again and reuse the implementation of Things, but represent running Actions and also Events (like Alerts than can also have dynamic status (i.e., Properties) and need Actions such as confirm and resolve). I tried to skip Events on these for simplicity, but it's thinkable if there are use cases.

Because "Thing" and "Thing Description" for something that is not a Thing is very confusing and creates headaches for our semantic guys (hi @vcharpenay), I would like to propose the following:

1. Generalize the concepts, mechanics, and some vocabulary of Thing Description to "Entitiy Description"
2. Make Thing Description a type of Entity Description (having "@type": "Thing" makes more sense, too)
3. Introduce "Action Description" as another type of Entity Description that describes invoked Actions. It could still use the application/td+json media type and have ("@type": "Action"), but maybe there will be enough momentum to go toward application/wot+json (it is related to @mjkoster 's explanations in Comments on Simplified WoT Thing Description wot#393 (comment), as we start to also WoTify the runtime data exchanged (action result returned for invoking an Action, the actual Event data being pushed...).
4. Introduce "Event Description" as another type of Entity Description for Event instances ("@type": "Event").
5. Maybe this re-usable Entity Description format is also useful for others.

[mjkoster]

This is a good discussion point.

The second order pattern for actions and events involves defining resources that model instances of actions and events. That is, rather than an instance of an action or event being a payload that is consumed or emitted by a resource, the instance becomes a transient resource itself, with hypermedia affordances (a link that describes it, CRUD methods to model state changes...)

There are already good hypermedia patterns that can be re-used. If I create an action in an action collection using POST, I can get back a new hypermedia reference (link with href) to that action, which I can then observe to be informed of state changes (garage door is stuck 50% closed...) or normal completion. In the application this would return an observable rather than a promise. Of course, there is a a lot more design to do around who deletes them when they're not needed anymore, etc.

Likewise for events there would be a collection, which is in turn observable in the same way the raw event emitter resource was. We have discussed these patterns an, as Matthias said, decided to develop them over time and work out the first order patterns first, while keeping the long term requirement in mind. Hypermedia controls allow the second order patterns to be overlaid on the basic interaction models.

A protocol binding which is specified in a content format or some similar mechanism as in w3c/wot#393 (comment) can only make pre-ordained choices in many of these matters, where the "machine form" construct can be extended to allow runtime binding of different second order patterns. Both are valid hypermedia designs, one approach being like HTML, with a lot of transfer layer mapping pre-defined, and another approach which keeps the content serialization simple and adds a logically separate transfer control serialization (links and forms).

For example, HTML really only supports GET. Forms are needed to use POST and change state on the server.

We find the approach where the client is more involved in the transfer layer hypermedia controls (e.g. machine forms) to be good for separation of concerns and reuse of common formats (application/json) and common protocols (CoAP, HTML). This is accomplished by standardizing the extended functionality of hypermedia controls for the new use cases required to interact with connected things.

CoRE Pub/Sub is another example of using mostly hypermedia controls to overlay a high order interaction pattern onto basic REST.

[mkovatsc]

That is, rather than an instance of an action or event being a payload that is consumed or emitted by a resource, the instance becomes a transient resource itself, with hypermedia affordances (a link that describes it, CRUD methods to model state changes...)

Indeed. I am not sure if that came out clearly enough: When an Action Description is returned after invocation (or a 201 Created with a Location pointing to that Action Description) or an Event Description as Event data, then their respective Properties and Actions must be backed by dynamically created resources on the Thing.

The Action and Event Descriptions would also be able to carry static data in the place where TDs carry the metadata items: fields in the top level of the JSON-based document. Properties would hold dynamic data belonging to the Action/Event instances.

[sebastiankb]

non active issue anymore. @benfrancis posted that issue in the wrong repo. In addition, Action and Event Descriptions are out of the TD scope.