ContactsAPI Draft

Disclaimer: this isn't an endorsement. (Nor is it a complete review,
it's a quick scan.)

First, the biggest lesson that CoreMob can provide is that you should
*ALWAYS* provide (this means publishing) a UC/Requirements document
before working on any API. I think that the current discussion about
whether record() in the Call API makes sense is a good example of how
SysApps's failure to do so has led to confusion.

It's very hard to review any API proposal without such a document. I
can't understand why, e.g. a clear() method is needed.

> Abstract
> This specification defines a System Level API which offers a simple interface to manage user's contacts.

> A typical use case of the Contacts API is the implementation of an address book.

>From my perspective, an address book is an underlying data store.
Reading this API, it looks like what's being proposed isn't an API for
an Address Book, but for an Address Book *Manager*. Because what's
being exposed is a way to talk *TO* an address book, not to *be* an
address book.

To be constructive, I'd suggest "the implementation of an application
to manage a system's address book."

> 6. ContactsManager Interface

Given the first real interface is in fact a Manager, my previous note
about the Abstract being poorly phrased.

>             attribute EventHandler oncontactchanged;

This links to:

> 6.1 Attributes
> oncontactchanged of type EventHandler

There are no links from this to the related thing, which is really painful.

> 6.3 Event handlers

> The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the ContactsManager object:

> event handler / event handler event type
> oncontactchanged / contactchanged

There are no links from either of these to *anything*, which is even
more painful.

> 14. ContactChangeEvent Interface

Note that this is not spelled remotely like `contactchanged` in 6.3

> The ContactChangeEvent interface represents events related to a change in a contact.
> WebIDL[NoInterfaceObject]
> interface ContactChangeEvent : Event {
>     readonly attribute DOMString contactID;
> };

So, I'm worried about what happens when the system Contacts service
performs a "Contacts sync" and pulls in a few hundred contacts.

We had the equivalent problem with DOM Mutation Events, the end result
was Mutation observers [2] which support better batching (among other
things).

> A. References
> A.1 Normative references
> [DOM4] Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. URL: http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/
> [HTML5] Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
> [RFC2119] S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
> [WEBIDL] Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

There are no references to vCard 4. When Mozilla (tantek [3]) last
spent time discussing Contacts, it was adamant that vCard 4 be used
and referenced. I'm absolutely shocked and disappointed that it's
missing from any Mozilla related publication. Along with an
explanation for each and every deviation from vCard 4.

> 14.1 Attributes
> contactID of type DOMString, readonlyIndicates the identifier of the Contactobject [sic] that has changed.

Your markup is bad.


[1] http://sysapps.github.com/sysapps/proposals/Contacts/Contacts.html
[2] http://www.w3.org/TR/domcore/#mutation-observers
[3] https://wiki.mozilla.org/Tantek-Mozilla-projects#ContactsAPI

-- 
Sent from my mobile device

Received on Friday, 26 October 2012 15:57:52 UTC