Describe Gateway /things websocket endpoint #142
Conversation
In some places it would switch mid example so this replaces all instances of mythingserver with mywebthingserver since the latter was more common.
Fix WebThingsIO#46 Mirrors current gateway implementation. Also documents optional addition of `id` to WS messages.
There was a problem hiding this comment.
Thanks very much for drafting this, this is a much needed optimisation!
I recommend that we take a slightly different approach in order to make the gateway-wide WebSocket endpoint dynamically discoverable by WoT clients rather than a hard coded path (explained in the comments). This is dependent on creating a new gateway capability schema and will also require changes to the Web Thing REST API to replace the Things resource with links in a gateway's own Thing Description.
| @@ -917,6 +923,37 @@ <h3><code>event</code> message</h3> | |||
| </div> | |||
| </section> | |||
| </section> | |||
| <section> | |||
| <h2>Gateway WebSocket API</h2> | |||
There was a problem hiding this comment.
I don't think this should be a separate section of the specification. It should all be part of the Web Thing WebSocket API section, which may eventually become a separate W3C "Web Thing Protocol" specification to define a webthing WebSocket sub-protocol.
| <p>The Gateway WebSocket API acts as a broader version of the <a href="#web-thing-websocket-api">Web Thing WebSocket API</a> by allowing the client to open one WebSocket connection per Gateway instead of per Thing. The connection then acts as a multiplex of all the Gateway's Things' WebSocket connections. The <code>id</code> member is required for this channel to allow both the Gateway and the WebSocket client to determine with which Thing each message is associated. | ||
| <section> | ||
| <h3>Protocol Handshake</h3> | ||
| <p>To open a WebSocket on a Gateway, an HTTP GET request is upgraded to a WebSocket using a standard <a href="https://tools.ietf.org/html/rfc6455">WebSocket protocol</a> handshake and the "webthing" subprotocol. The WebSocket URL for a Gateway is the "/things" endpoint.</p> |
There was a problem hiding this comment.
Note that in section 3 it says "The specific URLs and URL structure of resources are defined by the Thing Description. This specification does not define a fixed URL structure."
It's important that the specification does not rely on hard coded paths like "/things" but instead has endpoints which can be dynamically discovered by a WoT client using any URL structure.
This section makes me realise that while WebSocket endpoints for individual devices can be discovered through the links section of a Thing resource, and a Thing resource can be discovered through links in the Things resource, there is no explicit mechanism for discovering the Things resource itself. We are assigning special behaviour to a resource just because it is called /things.
In Whistler we discussed an alternative approach to this where we treat the gateway itself as a web thing, with a gateway capability schema, and link to the things it manages via its own links member.
If we took this approach we could also provide a gateway-wide WebSocket endpoint in the links member of the gateway's Thing Description. This would ensure that once a client has the URL of the gateway's Thing Description it can discover the WebSocket endpoint directly, without having to rely on a hard coded path.
This approach also has the benefit of being able to define actions on the gateway itself such as "pair", "unpair" and "reboot".
Mirrors current gateway implementation and documents optional addition
of
idto WS messages.Also replaces mythingserver with mywebthingserver for consistency
Fixes #46