W3C home > Mailing lists > Public > public-device-apis@w3.org > November 2011

Re: Web API Design Cookbook

From: Robin Berjon <robin@berjon.com>
Date: Thu, 24 Nov 2011 12:13:07 +0100
Cc: "public-device-apis@w3.org public-device-apis@w3.org" <public-device-apis@w3.org>
Message-Id: <57B52745-7413-4167-AD17-540DA8AAB078@berjon.com>
To: "Poussa, Sakari" <sakari.poussa@intel.com>
Hi,

On Nov 22, 2011, at 19:52 , Poussa, Sakari wrote:
> Which would be the better style for asynchronous operations: callbacks or
> DOM events?

As you might have perceived from the cookbook, I am reluctant to answer that question definitively :) The only answer that works in all cases is "it depends".

> - Some W3C APIs (Contacts, Calendar, Messaging, Geolocation, ...) pass
> success/error callbacks as argument to methods.

Note that of those, only Geolocation is deployed  the others are likely to change, probably drastically.

> - Some more recent W3C specs (FileAPI, FileWriter, IndexedDB) use DOM
> Events.

They're not more recent actually, they're all in development as are those above.

The rule of thumb that I would give is this. If you expect either to need to cover (now or in the future) information beyond just success or error (e.g. indicating progress events, as in XHR) or if you might have multiple instances of success for a single call (e.g. being notified of messages that arrive) then you're better off with an events-based approach. It's more verbose, but it's more easily and elegantly flexible and extensible.

If however you will only get called once (e.g. you ask for some data, and at a point later in time you get it) then I would go with callbacks. However, I wouldn't use the Geo-like model which I find is less conducive to good practices and more verbose. I would use the NodeJS model (as outlined in the document), something like:

foo.getStuff(param, function (err, data) {
    // ...
});

Where "err" is null unless there's an error (and vice-versa). This helps encourage developers to actually handle errors (because they're right there) and it makes for very powerful consistency. If you look throughout the Node ecosystem, you will see that it works quite well.

I know that's not definitive, but does it help?

> Seems that Mozilla B2G is moving towards DOM events in their
> implementation [1].

I think that the jury is still out on this one, at least if I find the time to have a say :)

> Another question is related to notifications. That is,
> 
> - Some W3C APIs (geolocation, systeminfo) use watchChanges()/clearWatch()
> style with callbacks.
> 
> - Recent W3C specs ( FileAPI, FileWriter, IndexedDB, battery, sensors)
> uses DOM Events.
> 
> Any preferred way here as well?

For those I would go with events, because they are events. Using this infrastructure (when the data you're getting back really is an "event") means that you can reuse tools that work with events already, which most JS libs do.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon
Received on Thursday, 24 November 2011 11:13:39 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Wednesday, 9 May 2012 00:14:24 GMT