RE: [contacts] Contacts API update

Hi Richard, all,

Thanks Richard for update, and appreciate your efforts!

Here are my comments on the Dec 15th Editor's Draft:
(Excuse me if some of them are very nit-picky :-))

1) Abstract: 
- Change "unified" to "device". I think we are really defining access to
device address book. And this term should be inline with the interface
names used in the spec e.g. "Device", DeviceContacts". And this does not
preclude the sources from which the contacts were obtained. Proposed
sentence: "This specification defines an API that provides access to the
user's device address book data."

2) Introduction: 
- Proposed re-write: "The Contacts API defines a high-level interface to
provide access to the user's device contact information, such as names,
addresses and other contact information. The API itself is agnostic of
any underlying address book sources and data formats."

3) 4.1 DeviceContacts interface:
- Missing hyperlink for the term Contacts in "the Contacts interface".
- remove the word "typically", and use a SHOULD or MUST.

4) 4.2 Contacts Interface
- Use of the term interface twice in the first sentence is redundant. I
would rephrase this to "The Contacts interface provides a handle to the
device address book (i.e. a set of one or more contacts associated with
the address book), such that they may be created, read, updated, deleted
and searched."
- Contacts.create: an optional parameter that takes a 'seviceId' would
be useful to create a contact on a per service basis. Otherwise, it is
not possible to say if I want to create a new contact for a particular
serviceId. Alternatively, this can be supplied at the time of adding to
the address book.
- Would renaming to "Contacts" to "Address Book" reflect better? Right
now we have "Contact" and "Contacts" interfaces which can be easily
mis-typed.

5) 4.3 Contact Interface
- rename 'commit' method to 'add' - it is more intuitive!
- To minimize the interfaces, Contact properties interface can be
collapsed with the Contact interface. I don't see a significant value
for Contact to extend Contact properties.
- A new remove() method will the 'commit' method, right? 
- Moving the commit/add(), remove() to Contacts interface is something
to consider.

6) 4.4 ContactResult
- This interface has very little use if the remove() is moved to either
Contacts or Contact interface. The only other use currently is to hold
the results from search for which we could just use the find method to
return a sequence of Contact objects.

7) 4.6 ContactNode
- Unfortunately, the name of this interface doesn't give a hint of what
it does. Perhaps renaming it to "ContactField" or similar is better to
indicate that this object is representing a field within a contact?
- Rephrase to "The ContactNode/Field interface is a reusable component
that is used to support the contact fields within a Contact Object. It
defines an optional type parameter that can be provided with a standard
value.

8) 4.7 ContactOptions
- Rename this to "ContactSearchFilter" or similar. 
- The options provided in this interface seem to be fairly generic in
nature and wondering if we could provide a generic search framework that
can be used across all APIs (e.g. contacts, calendar, messaging, etc.)

Regards,
Suresh

-----Original Message-----
From: public-device-apis-request@w3.org
[mailto:public-device-apis-request@w3.org] On Behalf Of
richard.tibbett@orange-ftgroup.com
Sent: Friday, December 11, 2009 10:03 AM
To: public-device-apis@w3.org
Subject: [contacts] Contacts API update

Hi,

I've just uploaded the latest draft of the Contacts API following
feedback from the group: http://dev.w3.org/2009/dap/contacts/

A summary of the changes is as follows (from the CVS log):

- Reduced scope of ContactProperties to be the intersection of existing
implementation property capabilities [1]
- Removed Contact interface constructor. Added 'create' factory method
to Contacts interface. [2] [3]
- Simplified representation of Contact interface name and addresses
attributes to a search-friendly flat-structure. [4]
- 'Contact Search processing rules' section editorial re-write. [5]
- Removed references to vCard. [6]
- Examples updated.
- Split SuccessErrorCallback interface in to multiple context-driven
callback interfaces.  
- Moved ContactError codes to GenericError interface.
- Updated Core Device references where required [7]

I have also made the following changes that require review from the DAP
group:

1. Added initial sorting and grouping to the ContactOptions interface.
(Please provide feedback to the list)
2. Removed Contacts.find() overloading due to addition of sorting and
grouping functionality and on the groups that OR functionality can be
adequately acheived via multiple find() requests. (Please provide
feedback to the list)
3. Added recommendation in 'Contact Search processing rules' section
that search matching SHOULD be loose (return substring matches) as
opposed to strict (return full attribute matches only).  (Please provide
feedback to the list)

In addition, it would be great to have some feedback on the included
'Security and Privacy Considerations' in the current specification.

I have not currently added a convenience function to create 'complex'
ContactProperties attributes though I'm happy to add a 'createNode'
helper method to the Contact interface if there is any request for this
in the coming week.

I look forward to further review and feedback on the mailing list. I
will aim to remedy any outstanding issues in preparation for a proposed
FPWD publication in the very near future.

Kind Regards,

Richard


[1]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0010.html

[2]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0112.html

[3]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0017.html

[4]
http://lists.w3.org/Archives/Public/public-device-apis/2009Nov/0253.html

[5]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0001.html

[6]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0015.html
(on working on a smaller set of attributes)

[7]
http://lists.w3.org/Archives/Public/public-device-apis/2009Dec/0054.html



---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.

Received on Tuesday, 15 December 2009 21:17:17 UTC