Promises - review of use in Network Service Discovery draft?

Dear TAG members (cc'd DAP):

The Device API working group (DAP) is working on a specification 'Network Service Discovery'.

"This specification defines a mechanism for an HTML document to discover and subsequently communicate with HTTP-based services advertised via common discovery protocols within the current network."

<https://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html>

Rich Tibbett, the editor, has updated the editors draft to use 'Promises' as noted in his message below.

Would members of the TAG that have experience with Promises please (if possible) review the Promises usage in this editors draft and let the DAP WG know of any concerns or best practices that we need to consider (or confirm that our usage looks good)?

Thanks

regards, Frederick

Frederick Hirsch, Nokia
Chair, W3C DAP Working Group

For Tracker, this completes ACTION-644

Begin forwarded message:

> Resent-From: <public-device-apis@w3.org>
> From: ext Rich Tibbett <richt@opera.com>
> Date: July 23, 2013 4:45:40 AM EDT
> To: Device APIs Working Group <public-device-apis@w3.org>
> Subject: Re: [discovery] getNetworkServices should return a Promise instead of callbacks.
> 
> On Fri, Jul 19, 2013 at 2:10 PM, Rich Tibbett <richt@opera.com> wrote:
>> We should consider adopting a Promise-based approach for the Network
>> Service Discovery API instead of holding on to callbacks. This change
>> affects one method in the API: navigator.getNetworkServices.
>> 
>> The change would be to replace the WebIDL included in Section 4 [1]
>> with the following *much simpler* WebIDL block:
>> 
>> [Supplemental, NoInterfaceObject]
>> interface NavigatorNetworkService {
>>  Promise getNetworkServices( in any type );
>> };
>> Navigator implements NavigatorNetworkService;
>> 
>> Where the value of the promise would resolve to a NetworkServices object [2].
>> 
>> Usage may be as follows:
>> 
>> navigator.getNetworkServices("...NSD search
>> string...").then(showServices, handleError);
>> 
>> This change would significantly reduce the amount of WebIDL we need to
>> maintain in this specification in support of a callbacks model. It
>> means implementations can inherit from the web browsers Promises
>> infrastructure [3]. Re-using Promises would likely make implementation
>> of this API significantly less difficult, lead to more consistency
>> across different implementations (assuming each browser implements the
>> lower-level Promises API in compatible ways) and leave less room for
>> NSD API implementation confusion [4].
> 
> There seems to have been general consensus on this mailing list in
> favor of this change so I have gone ahead and updated the WebIDL and
> associated algorithms in the NSD API specification accordingly. The
> latest editor's draft is available in the usual place
> (https://dvcs.w3.org/hg/dap/raw-file/tip/discovery-api/Overview.html).
> 
> br/ Rich
> 
>> 
>> [1] http://www.w3.org/TR/discovery-api/#requesting-networked-services
>> 
>> [2] http://www.w3.org/TR/discovery-api/#networkservices
>> 
>> [3] http://dom.spec.whatwg.org/#promises
>> 
>> [4] For example, I've seen discussions on this mailing list asking
>> e.g. whether success callbacks fire only once or are able to fire
>> multiple times against a single call to getNetworkServices(). Promises
>> only resolve once and that matches the original intended behavior of
>> the successCallback argument to getNetworkServices. Using Promises
>> therefore would implicitly re-enforce such assumptions without needing
>> to be overly explicit of those intentions in this API itself.
>

Received on Wednesday, 24 July 2013 15:13:40 UTC