Talk:WebAPI/ContactsAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
Line 1: Line 1:
== philikon's PoCo-based proposal ==
== philikon's PoCo-based proposal ==


It's probably not worth it to bikeshed over the data schema, though I
has moved to https://github.com/philikon/webcontacts/tree/master/idl
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 [http://portablecontacts.net/draft-spec.html 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.)

Latest revision as of 23:35, 18 November 2011

philikon's PoCo-based proposal

has moved to https://github.com/philikon/webcontacts/tree/master/idl

Retrieved from "https://wiki.allizom.org/index.php?title=Talk:WebAPI/ContactsAPI&oldid=371338"