Talk:WebAPI/ContactsAPI

philikon's PoCo-based proposal

It's probably not worth it to bikeshed over the data schema, though I do feel the one defined in PoCo is slightly more concise (using 'name.formatted' instead of displayName, defining individual fields for addresses, etc.). But, really, the other ones are close enough to that one that it probably doesn't matter. It's just a matter of picking one :)

As for the API, I propose the following JS adaption of the PoCo API for the navigator.contacts object:

 interface Contacts {
   void find(in ContactFindCB successCb,
             in ContactErrorCB errorCb,
             in ContactFindOptions options);
   void create(in ContactSuccessCB successCb,
               in ContactErrorCB errorCb,
               in Contact contact);
   void update(in ContactSuccessCB successCb,
               in ContactErrorCB errorCb,
               in Contact contact);
   void delete(in ContactSuccessCB successCb,
               in ContactErrorCB errorCb,
               in Contact contact);
 }

Unlike in the WAC proposal, all manipulation methods (create, update, delete) take the same kind of callback as defined here:

 [function]
 interface ContactSuccessCB {
   void onsuccess(in DOMString id);
 }

As for the 'find()' method, the 'fields', 'filter', and 'options' parameters that are present in various API specs are merged into a single ContactFindOptions object whose interface is based on the PoCo query API:

 interface ContactFindOptions {
   /* presentation */
   DOMString[] fields;
   
   /* filtering */
   DOMString[] filterBy;
   DOMString filterOp;
   DOMString filterValue;
   Date updatedSince;
   
   /* sorting */
   DOMString sortBy;
   DOMString sortOrder;
   
   /* pagination */
   long startIndex;
   long count;
 }

Please refer to the PoCo spec for details on those fields. My only alteration is to make filterBy and sortBy arrays to allow filtering/sorting by multiple fields simultaneously. Implementations may not necessarily have to support this, but it's easy enough to spell the API this way from the start. In fact, implementations may not have to support all querying features from the start; likewise they could support additional features by supporting more attributes on the ContactFindOptions object. (I imagine queries by metrics like "recently interacted with" could be very useful.)