Add directory of things

[benfrancis]

As a user I want to add a directory of web things my list of things so that I don't have to manually add each thing in turn.

Implementation of https://w3c.github.io/wot-discovery/#exploration-directory

[benfrancis]

Note that a Web of Things gateway like WebThings Gateway should be exposed as a WoT Directory, with a Thing Description describing the capabilities of the gateway and providing its list of things as a property.

Gateways would therefore be added to the app as a directory.

If we want to be backwards compatible with WebThings Gateway 1.x we'll need to figure out how to do this without a Thing Description, perhaps by using the /things endpoint directly since there's no machine-readable JSON resource currently served at the root of a gateway's domain.

[benfrancis]

Some initial ideas for the UI to add a directory/gateway:

1. Tap "+"
2. Enter web thing URL of gateway (eventually this will the URL of the gateway's Thing Description, but for 1.x gateways we're going to have to fake that somehow and just provide the gateway domain)
3. Tap "Submit"
4. (Detects that the Thing is a Gateway (eventually via a new gateway capability schema, but for 1.x gateways we might have to fake it)
5. Edit gateway title and click "Add" (it may have to just default to "WebThings Gateway" for now)
6. (The gateway title appears as a heading, and all of the devices from the gateway are added as individual Things under that heading)

Open questions:

1. Not all Things of @type ThingDirectory will be gateways. We may have to have a generic "Directory" type as well as the "Gateway" type which would be differentiated using a semantic annotation.

[arist0v]

Did we start discovering ThingsDirectory or we just add it provding the url and login(for a gateway)
and on a later part add discovering feature

[benfrancis]

One of the challenges of adding a ThingDirectory (gateway) as opposed to individual Things (devices) is that in the Web Thing API there is currently no resource which represents the directory/gateway itself.

This will be solved in 2.x by WebThingsIO/gateway#2927, which is part of implementing the WoT Discovery specification. Maybe we could solve that earlier by adding a simpler non-standard Thing Description for the gateway in 1.1.

Another challenge (which also applies to adding individual Things) is how to handle authentication/authorisation when adding a directory which requires authentication. This is something we're working on solving for the WoT Discovery specification in w3c/wot-discovery#135.

The way that will probably work is that an initial HTTP GET request on the gateway's URL (e.g. https://example.webthings.io) will reply with a 401 Unauthorized response which will include metadata that tells the client (in this case the WebThings App) how to authenticate to access the directory. In the case of WebThings Gateway, this would provide OAuth2 metadata which the client would then use to display the gateway's login page so that a JSON Web Token can be generated for the client. The client would then re-send the GET request on the gateway's URL with the JWT in an Authorization header and it would respond with the Thing Description of the Directory, which includes a Form with an API endpoint for listing all of its Things.

Currently none of this is possible because with WebThings Gateway 1.0 if you send a GET request to https://example.webthings.io you'll just get an HTML page which isn't very useful.

Until we add a Thing Description for the gateway (which is a much better approach because it can provide additional metadata about the gateway such as its name), the only way I can think of making this work in the app is to fetch the Things resource of the gateway instead. If you send a GET request to https://example.webthings.io/things with an Accept header set to application/json you will get a JSON array of Thing Descriptions.

You also need to solve the authentication problem, and the only way you can really work around that is to manually enter a JSON Web Token into an additional field in the form when adding a directory to the app. I'd really rather not implement that if we can avoid it because it would be very difficult to use.

All of this should be much easier with WebThings Gateway 2.x...

[arist0v]

What i suggest, is create the ThingsDirectory (gateway) library and handling it only as a gateway, when we will be ready to change this to gateway v2.0(or maybe having both) we can then edit this library only to make it compatible