Describe the possible/allowed combinations of (un)observingall properties

[danielpeintner]

At the moment it is not clearly stated what the allowed operations for (un)observingallproperties are, e.g.:

• After the one operation for observeall a client is allowed to only request unobserveall, or could it also unobserve properties one by one
  • or the other way around. observe(property1) and observe(property2), can I call unobserveall ?
  • clarify the allowed "pairing"
• When one property changes
  • returning all properties
  • returning just the property that has been changed
  • ...

Coming from w3c/wot-scripting-api#312

[benfrancis]

@danielpeintner wrote:

After the one operation for observeall a client is allowed to only request unobserveall, or could it also unobserve properties one by one

This may depend on the underlying protocol.

With Server-Sent Events for example, unobserveproperty or unobserveallproperties operations are carried out by simply dropping an open HTTP connection(e.g. see the HTTP SSE Profile)). If you start observing all properties with GET /properties, there isn't really a mechanism to stop listening to only one of those properties. Once an SSE connection is set up, it is unidirectional.

With WebSockets it's possible that a sub-protocol (e.g. the Web Thing Protocol) could allow you to observe all properties in one message, and then unobserve one of those properties in a separate message. WebSockets are bi-directional.

With Webhooks it depends on how the subscription mechanism is designed. In the HTTP Webhook Profile for example you unsubscribe using a subscription ID from a subscription, so if you observed all properties you could only unobserve all properties at once. Webhooks don't necessarily have to work this way though because they aren't standardised.

I believe with CoAP Observe a client just "forgets" a subscription, then the next time a server sends a value the client doesn't acknowledge it and the server de-registers the observation. That probably means you can only unsobserveallproperties after a observeallproperties operation and not unobserve an individual property.

This all applies to subscribing to events as well as observing properties.

In conclusion, I don't think the Thing Description can constrain this either way - it needs to be protocol specific.

When one property changes
returning all properties
returning just the property that has been changed

My assumption has always been that you just send the one property value. That may also be limited by the underlying protocol, but I can't think of an example.

The semantics/payload format for doing this is definitely not well defined in the Thing Description specification though.

The HTTP SSE Profile defines a specific binding for this by putting the name of the property/event in the event field of an event payload and the value in the data field.

The event payload format is currently undefined in the HTTP Webhook profile because we couldn't agree on a payload format. It's very challenging to define such a payload format declaratively in a Thing Description in an unambiguous way.

--

I think all of these kinds of details need to be defined in a protocol binding document.