Skip to content

Commit

Permalink
Update text and examples regarding the fetching of TDs (#524)
Browse files Browse the repository at this point in the history
  • Loading branch information
@JKRhb
JKRhb authored Jan 15, 2024
1 parent 6482a8c commit d0c5f8c
Showing 1 changed file with 42 additions and 27 deletions.
69 changes: 42 additions & 27 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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=].
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand Down

0 comments on commit d0c5f8c

Please sign in to comment.