Explain Websocket binding ideas

The Thing Description specification doesn't currently provide any examples of how to describe a WebSocket API endpoint in a Form. The Binding Templates note provides sequence diagrams for the specific use cases of subscribing to events and observing properties over a WebSocket, but these are not particularly realistic examples because they assume that each interaction affordance has its own WebSocket URL and that only raw data as defined in the property or event data schema is sent over the socket.

In my experience for efficiency reasons it is more common for a web thing to share a WebSocket connection between multiple operations, and even for multiple web things to share a single WebSocket connection. It might be useful to provide examples of best practices for how to refer to a WebSocket endpoint in a Thing Description. For example, is there a recommended way to link to a single WebSocket endpoint which is used for multiple operations across multiple properties, actions and events?

Mozilla's implementations currently refer to a single WebSocket endpoint for a thing using an "alternate" link relation in a top level Link object in the Thing Description. e.g.

"links": [
  {
    "rel": "alternate",
    "href": "wss://mywebthingserver.com/things/lamp"
  }
]

However, because a WebSocket is really just a raw TCP socket with no protocol semantics this requires that the client has prior knowledge of how messages are encoded in order to differentiate between different messages for different operations (including error conditions) and even different things. A WebSocket URL alone is not enough information for a client to know how to communicate with a web thing.

The Binding Templates note says that "For WebSockets, the IANA-registered Websocket Subprotocols [iana-web-socket-registry] may be used" in the subprotocol member of a Form, so that could be one way to provide this information. E.g.

  "forms": [{
      "href": "wss://mywebthingserver.com/things/lamp",
      "subprotocol": "myspecialprotocol",
      "op": ["readproperty", "writeproperty", "observeproperty", "unobserveproperty", "invokeaction", "subscribeevent", "unsubscribeevent", "readallproperties", "writeallproperties", "readmultipleproperties", "writemultipleproperties"]
  }]

Note that the Web Thing Protocol Community Group is working on a concrete WebSocket sub-protocol specifically designed for the Web of Things.

w3c / wot-binding-templates

Explain Websocket binding ideas #100