RE: APIs Design patterns

Hi Dom,

Thanks for your feedback.
It helps.
I will dive deeper into your proposals soon.

Thanks,
Marcin

Marcin Hanclik
ACCESS Systems Germany GmbH
Tel: +49-208-8290-6452  |  Fax: +49-208-8290-6465
Mobile: +49-163-8290-646
E-Mail: marcin.hanclik@access-company.com

-----Original Message-----
From: Dominique Hazael-Massieux [mailto:dom@w3.org]
Sent: Thursday, November 19, 2009 9:35 AM
To: Marcin Hanclik
Cc: public-device-apis@w3.org
Subject: APIs Design patterns

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



________________________________________

Access Systems Germany GmbH
Essener Strasse 5  |  D-46047 Oberhausen
HRB 13548 Amtsgericht Duisburg
Geschaeftsfuehrer: Michel Piquemal, Tomonori Watanabe, Yusuke Kanda

www.access-company.com

CONFIDENTIALITY NOTICE
This e-mail and any attachments hereto may contain information that is privileged or confidential, and is intended for use only by the
individual or entity to which it is addressed. Any disclosure, copying or distribution of the information by anyone else is strictly prohibited.
If you have received this document in error, please notify us promptly by responding to this e-mail. Thank you.

Received on Thursday, 19 November 2009 09:27:41 UTC