Re: ContactsAPI Draft

On Fri, Oct 26, 2012 at 8:57 AM, timeless <timeless@gmail.com> wrote:
> 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.

To be clear, we haven't started working on these API yet.  We're just
gathering proposals.

If you'd like to contribute use cases for the Contacts API, we have
some space allocated on the wiki:

http://www.w3.org/wiki/System_Applications_WG:_Contacts_API

Please feel encouraged to contribute use cases there.

If there is significant disagreement about which use cases we ought to
support, we can work on a use cases / requirements document before
taking up work on an API proposal.

Adam


>> 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 21:50:17 UTC