Update text and examples regarding the fetching of TDs (#524)

Author: JKRhb

index.html

@@ -382,7 +382,7 @@
       Implementations that use TypeScript or ECMAScript in a runtime to implement the APIs defined in this document MUST implement them in a manner consistent with the TypeScript Bindings defined in the TypeScript specification [[!TYPESCRIPT]].
     </p>
   </section>
-  
+
   <section> <h2>Terminology and conventions</h2>
     <p>
       The generic WoT terminology is defined in [[!WOT-ARCHITECTURE]]: <dfn data-lt="Things">Thing</dfn>, <dfn data-lt="Thing Descriptions">Thing Description</dfn> (in short <dfn>TD</dfn>), <dfn>Partial TD</dfn>, <dfn>Web of Things</dfn> (in short <b><i>WoT</i></b>),  <dfn>WoT Interface</dfn>, <dfn>Protocol Bindings</dfn>, <dfn>WoT Runtime</dfn>, <dfn data-lt="consume|consume a TD|consuming a TD">Consuming a Thing Description</dfn>, <dfn>TD Directory</dfn>, <dfn data-lt="Properties">Property</dfn>, <dfn data-lt="Actions">Action</dfn>, <dfn data-lt="Events|WoT-Event">Event</dfn>,
@@ -489,19 +489,20 @@ <h2>The <dfn>ThingDescription</dfn> type</h2>
       [[!WOT-TD]]. It is expected to be
       a <a data-cite="infra#parse-json-bytes-to-a-javascript-value">parsed JSON object</a> that is validated using <a data-cite="WOT-TD#json-schema-for-validation">JSON Schema validation</a>.
     </p>
-    <section> <h3> Fetching a Thing Description</h3>
+    <section> <h3> Requesting a Thing Description</h3>
       <p>
-        Fetching a <a>TD</a> given a URL should be done with an external method, such as the <a data-cite="fetch#fetch-api">Fetch API</a> or a HTTP client library, which offer already standardized options on specifying fetch details.
+        Requesting a <a>TD</a> given a URL should be done with the
+        <a href="#dom-wot-requestthingdescription">requestThingDescription()</a>
+        method.
+        Alternatively, external methods, such as the <a data-cite="fetch#fetch-api">Fetch API</a> or an HTTP client library, can be used.
       </p>
-      <pre class="example" title="Fetching a Thing Description">
+      <pre class="example" title="Requesting a Thing Description">
         try {
-          let res = await fetch('https://tds.mythings.biz/sensor11');
-          // ... additional checks possible on res.headers
-          let td = await res.json();
-          let thing = await WOT.consume(td);
+          const td = await requestThingDescription('https://tds.mythings.biz/sensor11');
+          const thing = await WoT.consume(td);
           console.log("Thing name: " + thing.getThingDescription().title);
         } catch (err) {
-          console.log("Fetching TD failed", err.message);
+          console.log("Requesting TD failed", err.message);
         }
       </pre>
     </section>
@@ -844,7 +845,7 @@ <h3>Validating an ExposedThingInit</h3>
           and stop.
         </li>
         <li>
-          If fetching a <a>Thing Description</a> is not supported by the
+          If requesting a <a>Thing Description</a> is not supported by the
           implementation, [=reject=] |promise| with {{NotSupportedError}} and
           stop.
         </li>
@@ -2023,13 +2024,13 @@ <h3>The <dfn>subscribeEvent()</dfn> method</h3>
         It returns a {{Promise}} to signal success or failure.
         <p class="ednote">
           This algorithm allows for only one active {{Subscription}} per <a>Event</a>. If a new
-          {{Subscription}} is made while an existing {{Subscription}} is active the runtime 
-          will throw an {{NotAllowedError}}. 
+          {{Subscription}} is made while an existing {{Subscription}} is active the runtime
+          will throw an {{NotAllowedError}}.
         </p>
         The method MUST run the following steps:
         <ol>
           <li>
-            Let |thing| be the reference of this {{ConsumedThing}} object. 
+            Let |thing| be the reference of this {{ConsumedThing}} object.
           </li>
           <li>
             Return a {{Promise}} |promise:Promise| and execute the next steps [=in parallel=].
@@ -2322,7 +2323,7 @@ <h4>The <dfn>stop()</dfn> method</h4>
                 <li>
                   [=Resolve=] |promise|.
                 </li>
-              </ul> 
+              </ul>
             </li>
             <li>
               If the underlying platform receives further notifications for this
@@ -2772,7 +2773,7 @@ <h3>The <dfn>PropertyReadHandler</dfn> callback</h3>
                 Let |handler:function| be `null`.
               </li>
               <li>
-                If there is a user provided {{PropertyReadHandler}} in {{ExposedThing/[[readHandlers]]}} <a>internal slot</a> 
+                If there is a user provided {{PropertyReadHandler}} in {{ExposedThing/[[readHandlers]]}} <a>internal slot</a>
                 for |interaction|, let |handler| be that.
               </li>
               <li>
@@ -3480,7 +3481,7 @@ <h3>The <dfn>EventSubscriptionHandler</dfn> callback</h3>
         </ol>
       </div>
     </section>
-    
+
     <section> <h3>Handling <a>Events</a></h3>
       <div>
         When an <a>Event</a> with name |name| is emitted with
@@ -3500,8 +3501,8 @@ <h3>The <dfn>EventSubscriptionHandler</dfn> callback</h3>
                 its |options|.
               </li>
               <li>
-                  If |data| is `undefined`, assume that the notification |response| 
-                  will contain an empty data payload as specified by <a>Protocol Bindings</a>. 
+                  If |data| is `undefined`, assume that the notification |response|
+                  will contain an empty data payload as specified by <a>Protocol Bindings</a>.
               </li>
               <li>
                 If the underlying protocol stack permits conveying event errors and
@@ -4259,9 +4260,8 @@ <h2>API design rationale</h2>
           represented indirectly.
         </p>
         <pre class="example" title="Open a lock">
-          let res = await fetch(‘https://td.my.com/lock-00123’);
-          let td = await res.json();
-          let lock = new ConsumedThing(td);
+          const lockTd = await WoT.requestThingDescription('https://td.my.com/lock-00123');
+          const lock = WoT.consume(lockTd);
           console.log(lock.readProperty('status'));
           lock.invokeAction('open', 'withThisKey');
         </pre>
@@ -4280,16 +4280,31 @@ <h2>API design rationale</h2>
         into consideration when designing a Scripting API for WoT.
       </p>
     </section>
-    <section> <h4>Fetching and validating a TD</h4>
+    <section>
+      <h4>Requesting and validating a TD</h4>
       <p>
-        The <code>fetch(url)</code> method has been part of this API in earlier versions. However, now fetching a <a>TD</a> given a URL should be done with an external method, such as the <a data-cite="fetch#fetch-api">Fetch API</a> or a HTTP client library, which offer already standardized options on specifying fetch details. The reason is that while simple fetch operations (covering most use cases) could be done in this API, when various fetch options were needed, there was no point in duplicating existing work to re-expose those options in this API.
+        The current version of this specification defines a new
+        `requestThingDescription` method that simplifies the process of
+        retrieving and validating a Thing Description.
+        However, it only covers simple use cases that do not require additional
+        parameters or special HTTP headers for the retrieval.
       </p>
       <p>
-        Since fetching a <a>TD</a> has been scoped out, and <a>TD</a> validation
-        is defined externally in the [[[WOT-TD]]] specification, that is scoped out, too.
-        This specification expects a <a>TD</a> as
-        <a data-cite="infra#parse-json-bytes-to-a-javascript-value">parsed JSON object</a> that has been validated according to the [[[WOT-TD]]] specification.
+        More sophisticated use cases need to be covered by external methods, such
+        as the <a data-cite="fetch#fetch-api">Fetch API</a> or an
+        HTTP client library, which offer already standardized options on
+        specifying fetch details.
+        In these cases, the user is required to perform validation manually as
+        described by the [[[WoT-TD]]] specification.
       </p>
+      <p class="ednote" title="Extending the `requestThingDescription()` method">
+        In the future, `requestThingDescription()` might be extended with an
+        `options` argument, including frequently used `fetch` options.
+        Please
+        <a href="https://github.com/w3c/wot-scripting-api/issues/new">
+          open an issue
+        </a> to request support for options.
+    </p>
     </section>
     <section> <h4>Observers</h4>
       <p>