Re: Web API Design Cookbook

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 UTC