Split registration event into multiple events

[benfrancis]

This PR proposes splitting the registration event of the Directory Service API into three separate events: thingCreated, thingUpdated and thingDeleted. As discussed in #133.

The rationale for combining these three event types into a single event in the first place was to make it easier to subscribe to all events at once. But this feels like an anti-pattern which is motivated by needing to work around limitations of the WoT Thing Description specification. It also makes it impossible for a Consumer to subscribe to individual events if that's what they want to do.

A normative Thing Description or Thing Model specified by the WoT Working Group should demonstrate best practices, and taking the combined approach may imply that it's a good practice for Web Things to combine all their event types into a single event to make it easier to subscribe to all events at the same time.

I have instead proposed new subscribeallevents and unsubscribeallevents operations for the Thing Description specification so that it could be possible to either subscribe to all events, or to individual events, depending on what the Consumer prefers. See #1082.

---

Preview | Diff

[farshidtz]

It also makes it impossible for a Consumer to subscribe to individual events if that's what they want to do.

They can subscribe to individual events. I guess you meant it is impossible to un-subscribe from individual events?

Though that is also possible. A client can unsubscribe separately if they have subscribed the same way.

[farshidtz]

The event format and query arguments were changed recently (#155). It would be great if you could propose your changes based on the latest spec.

[mmccool]

Query approach is more extensible (can add new event types without changing the API) and maps better to MQTT (point from @farshidtz).

[farshidtz]

Example new event type given by @mmccool: TD expiry.

[benfrancis]

@mmccool Do you think it's good practice to combine all event types that a device emits into a single event affordance?

I would argue adding an event type changes the API regardless of the URL structure used to subscribe to events. Either way a Consumer still need modifying to support the new event type.

Regarding MQTT, see my comment at #158 (comment)

[farshidtz]

I would argue adding an event type changes the API regardless of the URL structure used to subscribe to events. Either way a Consumer still need modifying to support the new event type.

This is small technical issue and indeed a good point. We should write in the spec that servers can add other events types and clients should ignore anything that they don't recognize.

Regarding MQTT, see my comment at #158 (comment)

The current PR is about notifications which is very well relevant to MQTT. I think most implementations will end up using MQTT instead of SSE but we didn't specify that because we wanted to limit the first version to HTTP only and simplify the security (as far as I recall).

To expand my point about mapping to MQTT. There is no negotiation capability to request full or filter in MQTT, but the event type query will map this way:
SSE (HTTP Path) /events{?type} -> MQTT Topic events{/type}

[mmccool]

• actually opposite of consolidation...
• having separate interactions is more convenient in scripting API
• having single URL with query interface more convenient when working directly with URLs
• no reason we can't have both! - separate interactions, using common path/query interface underneath

[mmccool]

@farshidtz notes that this is based on an old version of the spec... so we can't necessarily merge at present

[benfrancis]

@farshidtz wrote:

There is no negotiation capability to request full or filter in MQTT

There's also no formal URI scheme, but that hasn't stopped people shoehorning MQTT IoT devices into a WoT Thing Description.

@mmccool wrote:

no reason we can't have both! - separate interactions, using common path/query interface underneath

Was there a conclusion about whether URLs are fixed in the specification or left down to the developer? I guess this is another matter of taste and it would be great if developers could choose their own URL design.

---

I think we're trying to solve different problems here. WebThings just needs a simple REST API for managing a list of things, for which events are probably not even strictly necessary. We have no plans to directly support consuming or exposing directories of Things using non-web protocols like MQTT (which we can support through adapters instead if necessary) and we have no plans to support the WoT Scripting API (because the already standard fetch() and WebSocket APIs are perfectly sufficient). It seems that the design of the Directory Service API is being complicated quite a lot by trying to make it protocol agnostic and also convenient to consume through the current (non-normative) WoT Scripting API.

In principle I like the idea of describing a directory with a Thing Description, but I'm afraid I don't think it's working very well. It requires some real API gymnastics to satisfy all of the above requirements, and also to try and describe a collection of resources for which the Thing Description specification doesn't really have the necessary semantics.

I'm struggling to think of a path forward in the current direction which would result in a Directory Service API we'd want to implement in WebThings, so in the interests of being constructive I've come up with an alternative proposal. See #172

[benfrancis]

Superseded by #184