Improving event type values in the Notification API

[farshidtz]

The Notification API supports three types of events.

The event types has specific names used in URI variables. These were changed recently and a pending proposal suggests yet another change. But before doing so, it is better to discuss pros and cons of every naming convention.

Convention A

WD1 used the following event types: created_td, updated_td, deleted_td

Note: This is before changing td to thing/things across APIs. In alignment to the current spec, those types would be: created_things, updated_things, deleted_things

Convention B (current)

The types were recently changed in response to feedback in F2F asking for simplifications (#155). The new types are similar to add and remove from the SSE spec examples: create, update, delete

Concerns:

• It doesn't convey any information about the payload. Since the payload of specific events in relevant protocols (SSE, WS, MQTT, CoAP observer) doesn't specify the content type, having type info in the event name is helpful. Adding thing prefix/suffix as in conventions A and C resolves that. On the other hand, we could assume that default events always contain TDs and add prefixes/suffixes for new possible content types.
• They are action verbs which sound strange in URIs and MQTT topics.

Convention C

One new proposal (#159 superseded by #184) suggests: thing_created, thing_updated, thing_deleted

This is an improvement to B but past tense verbs as prefixes is not so common and less readable (subscribing to thing created events?).

---

Taking a look at MQTT topic best practices and the event examples in TD spec, it looks like nouns are a more common choice. E.g. temperature, stats, status

That takes us to conventions D and E:

Convention D

thing_creation, thing_update, thing_deletion

This is very readable: subscribe to thing creation events:
/events?type=thing_creation (SSE):

Naively mapping it to an MQTT topic: things/creation/{id}

Convention E

Same as D but without the prefix: creation, update, deletion

---

For future extensions, I can think of:

• thing expiration
• thing movement
• directory status
• directory error

[benfrancis]

What makes most sense to me is:

1. Property names are nouns (e.g. things) because they describe an attribute of an object
2. Action names are simple verb phrases with either just a verb or a verb and an object (e.g. createThing), because they describe something that can be done to an object
3. Event names are past-tense verb phrases (e.g. thingCreated) because they describe something which has happened to an object

Some examples from the schemas we use in WebThings are "alarm", "doublePressed", "longPressed", "overheated".

However, looking at other event names in web specifications it appears that using past-tense verb phrases is not a common approach to naming events.

A more common approach would seem to be to simply call them "create", "update" and "delete" (Convention B, current) as with "click", "install", "copy", "open", "close" etc. Or possibly "thingcreate", "thingupdate", "thingdelete" like "compositionupdate", "timeupdate", "contentdelete". The latter sounds a bit clunky though.

Note that I used camelCase for the interaction affordance names in the Thing Description (as this is the convention in JavaScript/JSON), but event names themselves (e.g. to use over the wire or as the value of the type variable in the URL) tend to be all lower case with no separators between words.

[mmccool]

Current spec has nouns for events: thingDeletion, thingUpdate, thingCreate. Is this an acceptable convention now, and can we close this issue?

[farshidtz]

Current spec has nouns for events: thingDeletion, thingUpdate, thingCreate. Is this an acceptable convention now, and can we close this issue?

This issue is about the event type values used by the API. We currently have create, update, and delete in the spec.

[benfrancis]

I still think thingcreated, thingupdated, thingdeleted make the most sense from a linguistic point of view, especially since in this case it's useful to distinguish the events from the corresponding action names. But using verbs (create, update, delete) as event names does seem quite common in existing web specifications, as noted above.

[farshidtz]

@benfrancis:

A more common approach would seem to be to simply call them "create", "update" and "delete" (Convention B, current) as with "click", "install", "copy", "open", "close" etc. Or possibly "thingcreate", "thingupdate", "thingdelete" like "compositionupdate", "timeupdate", "contentdelete". The latter sounds a bit clunky though.

I am in favour of this and suggest we continue using verbs.

I'm just concerned with extensibility i.e. if an implementation wants to use the same API for other event types. With that in mind, thingcreate is more suitable than just create. Note that this string is used to subscribe and also to identify the received events when multiple event types are written on the same stream. In SSE, there is no content type for event data.

[benfrancis]

'm just concerned with extensibility i.e. if an implementation wants to use the same API for other event types. With that in mind, thingcreate is more suitable than just create. Note that this string is used to subscribe and also to identify the received events when multiple event types are written on the same stream.

FWIW thingcreated, thingupdated, thingdeleted also solves that problem. "Subscribe to 'thing created' events", "A thing was created".

[farshidtz]

'm just concerned with extensibility i.e. if an implementation wants to use the same API for other event types. With that in mind, thingcreate is more suitable than just create. Note that this string is used to subscribe and also to identify the received events when multiple event types are written on the same stream.

FWIW thingcreated, thingupdated, thingdeleted also solves that problem. "Subscribe to 'thing created' events", "A thing was created".

True. Any particular reason on not having a separator between the words? snake_case or kebab-case are both case-insensitive and suitable. Having no separator at all makes it hard to read or even programatically separate the object (thing) from the state (created/updated/deleted).

[benfrancis]

@farshidtz wrote:

Any particular reason on not having a separator between the words? snake_case or kebab-case are both case-insensitive and suitable. Having no separator at all makes it hard to read or even programatically separate the object (thing) from the state (created/updated/deleted).

Mostly just because that's what other web specifications do for event names. It's also what we do for operation names in the Thing Description specification. I don't have a strong opinion about it, just following convention.

[farshidtz]

I created a PR to change the naming convention to Convention C. Please review.
@benfrancis I went ahead with having a separator in the value for readability and easy handling in programs for client-side filtering. I realize that web specifications have the convention of appending words together, but don't understand how that is beneficial. I was unable to find that common beyond HTML/JS systems.