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

APIs Design patterns

From: Dominique Hazael-Massieux <dom@w3.org>
Date: Thu, 19 Nov 2009 09:34:44 +0100
To: Marcin Hanclik <Marcin.Hanclik@access-company.com>
Cc: "public-device-apis@w3.org" <public-device-apis@w3.org>
Message-ID: <1258619684.12107.1737.camel@localhost>
Hi Marcin,

Le mardi 17 novembre 2009 à 10:40 +0100, Marcin Hanclik a écrit :
> For DAP in [1] I propose the following consistency requirement (still [1] is a very early draft with bugs): [...]
> [1] http://dev.w3.org/cvsweb/~checkout~/2009/dap/design-patterns/Overview..html?rev=1.1&content-type=text/html;%20charset=iso-8859-1

Thanks for having started on the design patterns documents.
Here are some of my thoughts on what the document should be, and
possibly how it should be organized:
• I think the most useful thing the document should do is to record API
design issues that have arisen in WebApps, Geolocation and DAP (see
below for some examples), and document the outcome of the discussions
(with a clear guidance when there is one, or simply with cons and pros
when the outcome is not a clear cut)

• as a result, I would stay away from using RFC2119 keywords as much as
possible — I see the document as an opportunity to document and share
the experience we’re gathering across various groups, not as a
definitive and authoritative set of design requirements; ideally, the
document would be useful for us (when we start working on new APIs), for
newcomers to the group (to avoid re-hash discussions we have already
had), and on a larger scale for anyone who ends up having to design a
JavaScript API in the Web context (which we can imagine is a going to be
a growing set of people)

• I would split stylistic conventions into a separate section of the
actual design patterns

As an example of how I think we should discuss design issues in the
document:
<<<<<<
Asynchronous or synchronous API?
Synchronous APIs are generally easier to use than asynchronous APIs, but
defining an asynchronous API allows to build code that will not block
user interaction in a single-threaded environment. In particular,
asynchronous APIs calls are useful when:
• starting an operation that requires a noticeable time to complete
• starting an operation that requires a user’s action (e.g. giving
consent, or activating a control)
[@@@ side note: what impact have Web workers on that question?]
>>>>>>>>

I think we could discuss similarly most of the issues that have been
raised as “APIs - General” in Tracker [2]; for instance:
• Cancellable asynchronous operations (when are they useful? possible?
common WebIDL pattern?) [ISSUE-3]
• Events or Callbacks? (when to use which)
• Searchable data set (documenting the discussions we had on the
Contacts API) 
• API entry points (events, callbacks, markup, constructors) [ISSUE-44]
• Implicit user consent [related to ACTION-52]

I hope this is useful feedback.

Dom

2. http://www.w3.org/2009/dap/track/products/1
Received on Thursday, 19 November 2009 08:35:11 GMT

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