Describing common event subscription pattern such as subscriptionId

[danielpeintner]

The issue comes from the Scripting API were we try to keep complexity minimal to do event subscription (or any other interaction).

Having said that, we think the TD is underspecified when it comes to eventing.

Let's assume a rather common use-case for subscribing to events (see lifecycle below)

1. subscribe to event with options (e.g., a filter) and getting back a subscriptionId
2. events are reported
3. cancel subscription by the initially provided subscriptionId

The TD EventAffordance has 3 terms

1. subscription with one DataSchema (most likely describing the input? But how to properly describe output such the subscriptionId)
2. data with DataSchema describing the event content (seems fine)
3. cancellation with one DataSchema describing input such like subscriptionId (Question, do we need output here also?)

In general, we wonder whether it makes sense to collect some common use-cases (or eventing patterns) and try to experiment how these use-cases can be represented with the 3 aforementioned terms.

Issue relates to #817 and #812

[egekorkan]

Just for clarification on inputs and outputs for subscription and cancellation, the example from @sebastiankb uses the readOnly and writeOnly to indicate that some items are inputted to the device (writeOnly) and some items are only received from the device.

[danielpeintner]

Just for clarification on inputs and outputs for subscription and cancellation, the example from @sebastiankb uses the readOnly and writeOnly to indicate that some items are inputted to the device (writeOnly) and some items are only received from the device.

Mhh, maybe I wasn't super clear.
What I mean is where (and how) do I describe that when I subscribe to an event I get back a subscriptionId and it is of type string/integer or anything else...

[egekorkan]

Extract from the above example shows this:

"subscription" : {
    "type" : "object",
    "properties" : {
        "targetURL" : {
            "type" : "string", 
            "format": "uri",
            "writeOnly": true,                
            "description": "Requester provides the target URL to which Thing the event should be provided"
        },
        "subscriptionID" : {
            "type": "integer", 
            "readOnly": true, 
            "description": "Responses an unique subscription ID."
        }
    }
},

So the subscriptionID is received after the subscription but targetURI is sent for the subscription which are indicated by the readOnly and writeOnly fields.

I do agree that it is not how we are used to seeing things. If we think like this, everything in an action's input is "writeOnly":true and everything in an action's output is "readOnly":true" OR events should have input and output in subscription and cancellation fields.

[zolkis]

everything in an action's input is "writeOnly":true and everything in an action's output is "readOnly":true"

Or they could be default+unmutable values (documented in the TD spec).

[takuki]

To summarize discussion in March 27 TD call (minutes here):

• We need to experiment the most common event mechanism(s) in PlugFest.
• Such experiment should include event filtering and/or de-multiplexing.

Oracle implementation is in GitHub. (see here) . It was not clear whether this is a proprietary mechanism or it is based on some existing practices/standards. Any comments, @mlagally ?

[mlagally]

@takuki Thanks for the reminder. At this point it is a proprietary mechanism based on Webhooks.
I gave a presentation about the Oracle event mechanism around 1.5 years ago in a TD call.
@sebastiankb has this been archived?

[sebastiankb]

@mlagally do you have a date of presentation? then I can check the minutes.

[sebastiankb]

maybe we should also collect all (common) used event mechanism on the market such as

• WebSub: seems not to have an ID to mange the subscriptions
• Server-Sent Events: there is a initEvent, which also seems not to return an ID
• ...

[takuki]

* WebSub: seems not to have an ID to mange the subscriptions

In WebSub, unsubscribe request results in the hub contact you for verification.
In the unsubscribe request, the requester has to provide callback URL in hub.callback.

See Section 5.3 Hub Verifies Intent of the Subscriber of WebSub specification.