Provide a convenient way to fetch a TD in simple case

[zolkis]

As discussed on the Scripting call on 1 June 2020,

• currently the API relies on the Fetch Standard to fetch a TD given a URL.
• this decision was made because the multitude of possible options for the fetch.
• however, in real use cases fetching should be possible from a single URL.
• security details need not be shared via the API, since provisioning the runtime should take care of that.
• using Fetch in the "WoT-right" way is cumbersome for developers; while the option is still there, it would be nice to have a way to retrieve a TD given a URL.
• such a functionality would work not only with HTTP fetch, but also with CoAP (in the simple case, since in more complex cases an external library/function should be used).

In the past, the Scripting API had two ways to do this:

1. by a separate fetch() or fetchTD or fetchDescription() call that took a URL as a parameter and resolved with a parsed JSON object.
2. as a part of the consume() method (either a URL or a TD object was given as parameter).

Edit. Some historical discussions in these issues:
#162
#78

[zolkis]

In the second case, for HTTP the new consume() method could be implemented based on the current one as follows:

partial interface WoT {
  Promise<ConsumedThing>consume(
      (ThingDescription or ThingDescriptionURL) source, 
      optional ConsumeOptions options);
};

typedef (USVString or URL) ThingDescriptionURL;

dictionary ConsumeOptions {
  // here come the options we need
};

The consume options could come for instance from Fetch RequestInit. Currently we don't need them IMHO.

Also, URL is usually a string. However, it could also be a URL object. To be discussed.

Now how it affects the implementation: if source is a string (or a URL object), then try to fetch a TD from that, otherwise if it's an object, then use that for creating a new ConsumedThing.

function consume(source) {
  return new Promise((resolve, reject) =>
  {
      let td = null;
      if (typeof source === 'string' || source instanceof URL) {
        try {
          let res = await fetch(source);
          td = await res.json();
        } catch { reject( new TypeError) };
      } else if (typeof source === 'object') {
          td = source;
      } else reject(new TypeError);
      resolve(new ConsumedThing(td));
  });
};

[zolkis]

The other way would be a separate function that would leave the current implementation of consume() alone.

partial interface WoT {
  Promise<ThingDescription> retrieve(
      (USVString or URL) url, 
      optional RetrieveOptions options);
};

dictionary RetrieveOptions {
  // here come the options we need
};

And its implementation would be similar to the one above.

[zolkis]

Note that yet another way to obtain TDs is via discovery.
Perhaps we could merge this way of "directly fetching a TD" into the Discovery API (like "discover" a direct URL?). Let's say (using a speculative new discovery option),

let discovery = new ThingDiscovery(
    {  
        url: "https://mythings.org/sensor11", 
        method: "direct" 
    });
// note that fetch options could be merged with discovery options
do {
  let td = await discovery.next();
  console.log("Found Thing Description for " + td.title);
  let thing = new ConsumedThing(td);
  console.log("Thing name: " + thing.getThingDescription().title);
} while (!discovery.done);

It's another thing the Discovery API is going to likely change, so there are some options forward.

[zolkis]

@relu91 @danielpeintner @mmccool PTAL

[danielpeintner]

I see the point that the discovery work should provide means to easily get/retrieve a TD (and this might even change the following opinion in the future).

Having said that, I still like the current Scripting API approach that does not go into all those details how and where to retrieve a TD. The "assumption" is that once you do WoT.consume(TD) you have the TD already...

[relu91]

I have a positive feedback for the Discovery proposal. I think it blends quite well with what we have already. Plus it does not require to define a fetch like function. I still believe that we need this method even if COAP over UDP might cause some troubles...

[zolkis]

I have a positive feedback for the Discovery proposal.

Yes, I had the same thoughts just before checking on this issue :). Makes sense.
So I will leave this open and we will address it when we'll discuss discovery.

[danielpeintner]

Note: I suggest to remove the F2F label and re-label it with discovery and enhancement

[JKRhb]

I think we now have such a method in place, therefore I added the propose closing label :)

[zolkis]

Please add a ref to the PR that fixes this, and then close.

[relu91]

Call 11 Dec

• Fixed by this PR https://github.com/w3c/wot-scripting-api/pull/441/files