Open benfrancis opened 1 year ago
Remove the sentence: "Depending on the deployment scenarios and integration requirements for existing consumers, it may be required to use specific data payload formats (e.g. Cloud Events)." (The HTTP Webhook Profile needs to define a single payload format for events in order to guarantee out-of-the-box interoperability. Compatibility with existing consumers should be a non-goal.)
I'm really concerned if we would agree on a policy of having a non-goal to be compatible with the world as it exists.
I have been evaluating the latest draft of the Webhook Profile with a view to potential implementation in WebThings Gateway (Producer) and WebThings Cloud (Consumer) and I think it needs some more work before it's in an implementable state. I've provided my feedback section by section below, with action items as task list items which can be turned into separate issues if necessary.
10 HTTP Webhook Profile
So far there's only a protocol binding for events.
observeproperty
,unobserveproperty
,observeallproperties
andunobserveallproperties
(#376).10.1 Introduction
Suggested refinements:
10.1.1 Webhook Example
I think this example could use work. I'm not sure why the fireAlarm event would be fired when the button has been re-armed, and I'm not sure how a Consumer would know anything about sprinkler status. The cancellation payload format and unsubscribe protocol binding need updating to match the protocol binding in the specification text, i.e.
DELETE
instead ofPOST
and provide the subscription ID in the URL rather than the body (a DELETE request does not usually contain a body).10.4.1.1
subscribeevent
Content-Type
header to list of features of the subscription request, as in the exampleAlthough it's not mentioned in the normative text, the example shows the subscription ID being provided in the body of the HTTP response to the
subscribeevent
request. The problem with only including the ID in the body (as opposed to a URL) is that it requires a fixed URL design in order to know the subscription URL to which a Consumer should send an unsubscribeDELETE
request.I suggest that the response to the subscribe
POST
request should instead be201 Created
(since it creates a new subscription resource), and the URL of the new subscription resource should be included in aLocation
header. Theunsubscribeevent
operation can then send aDELETE
request to that URL (see below). This would be consistent with what we do for asynchronous actions in the HTTP Basic Profile.Accept
header fromsubscribeevent
operation request since it need not respond with a bodyContent-Type
header with valueapplication/json
in the POST request since it contains JSONsubscribeevent
operation to a201 Created
with the subscription URL in aLocation
headersubscribeevent
operationE.g.
10.4.1.2
unsubscribeevent
unsubscribeevent
operation to aDELETE
request on the subscription URL provided in theLocation
header of the response to thesubscribeevent
request, instead of prescribing a fixed URL formatAccept
header from theDELETE
request204 No Content
response to theDELETE
requestDELETE
request10.4.1.3
subscribeallevents
Accept
header from the subscription POST request, as withsubscribeevent
Content-Type
header with valueapplication/json
to the subscription POST request, since it contains JSONsubscribeallevents
operation to a201 Created
with the subscription URL in aLocation
headersubscribeevent
operationE.g.
10.4.1.4
unsubscribeallevents
DELETE /things/lamp/events
looks like it's trying to delete the events endpoints altogether rather than deleting a subscription to the events. Currently this operation also doesn't use the subscription ID provided in thesubscribeallevents
operation, so if there are multiple subscriptions the Web Thing won't know which one to remove.unsubscribeallevents
operation to aDELETE
request on the subscription URL provided in theLocation
header of the response to thesubscribeallevents
request, instead of on the events URLAccept
header from theDELETE
request204 No Content
response to theDELETE
requestDELETE
request10.4.2 Event Connections
POST
request with aContent-Type
header set toapplication/json
200 OK
response code (if the response contains a body) or an HTTP204 No Content
response code (if the response does not contain a payload).' This is not essential but would help Things to know whether there is a response body to process.Missing Features
The payload format for events still needs to be specified, but that is being discussed in #258. My proposal is at https://github.com/w3c/wot-profile/issues/258#issuecomment-1216599450.
The observe property protocol bindings need to be specified - I have filed #376.
There are also some additional features I think may help with scalability, for which I have filed separate issues: