WebAPI/ContactsAPI

From MozillaWiki
< WebAPI
Revision as of 06:22, 19 April 2012 by Anygregor (talk | contribs)
Jump to navigation Jump to search

Contacts API specification

Goals

Provide read/write DOM API access to the device address book, and the contacts contained therein with a simple minimal API that has a high-degree of interoperability with both device address books and commonly published web contact information (vCard4/hCard). - Tantek

Related:

  • W3C DAP work - similar but problematic. See the W3C DAP section below for how the ContactsAPI fixes key problems with the DAP approach.
  • A more "appy" Contacts API - that allows web apps to both access and be providers for contacts. This ContactsAPI is focused specifically on device contacts access for reasons of design simplification and prioritization for B2G. For exploring a broader / more 'appy' Contacts API see work on WebActions, WebActivities, and Labs/Contacts/ContentAPI.

The ContactsAPI is also known as WebContacts (or Contacts+).

Status

See bug 674720.

Proposed API

There is an object in window.navigator named mozContacts with the following interface: 

 interface ContactsManager
 {
   DOMRequest find(in ContactFindOptions options);
   DOMRequest clear();
   DOMRequest save(in Contact contact); // Success value is id? Or new Contact?
   DOMRequest remove(in Contact contact);
 };

 interface ContactFindOptions : nsISupports
 {
   attribute DOMString     filterValue;    // e.g. "Tom"
   attribute DOMString     filterOp;       // e.g. "contains"
   attribute DOMString[]   filterBy;       // e.g. "givenName"
   attribute DOMString     sortBy;         // e.g. "givenName"
   attribute DOMString     sortOrder;      // e.g. "descending"
   attribute unsigned long filterLimit;
 };

TO DO: Research/document device-specific address book capabilities and represent using methods on the ContactsManager interface.

The following Contact interface is based vCard4/hCard properties, flattened for the simple/typical case of one address (adr) based on the microformats 2.0 hCard iteration. 

 interface ContactAddress {
            attribute DOMString              streetAddress;
            attribute DOMString              locality;
            attribute DOMString              region;
            attribute DOMString              postalCode;
            attribute DOMString              countryName;
            attribute double                 latitude;
            attribute double                 longitude;
            attribute double                 altitude;
 };

 interface ContactProperties {
            attribute DOMString[]            name;
            attribute DOMString[]            honorificPrefix;
            attribute DOMString[]            givenName;
            attribute DOMString[]            additionalName;
            attribute DOMString[]            familyName;
            attribute DOMString[]            honorificSuffix;
            attribute DOMString[]            nickname;
            attribute DOMString[]            email;
            attribute DOMString[]            photo;
            attribute DOMString[]            url;
            attribute DOMString[]            category;
            attribute ContactAddress[]       adr;
            attribute DOMString[]            tel;
            attribute DOMString[]            org;
            attribute DOMString[]            jobTitle; /* 'title' from vCard made specific */
            attribute Date                   bday;
            attribute DOMString[]            note;
            attribute DOMString[]            impp; /* per RFC 4770, included in vCard4 */
            attribute Date                   anniversary; /* new in vCard4 */
            attribute DOMString              sex; /* new in vCard4, gender sub-component 1 */
            attribute DOMstring              genderIdentity'; /* new in vCard4, gender sub-comp 2 */
 };

 [Constructor(in ContactProperties properties)]
 interface Contact : ContactProperties
 {
   readonly attribute DOMString id;
   readonly attribute Date      published;
   readonly attribute Date      updated;
   Contact clone(); // Do we need this function? "new Contact(oldContact)" should just work
 };

Note: despite hCard2 including a flat set of adr properties into the top level h-card object for ease of publishing, this interface always abstracts those properties into a ContactAddress sub-object for simplicity (smaller/cleaner) of interface. The interface is able to represent published data.

Notes of properties left out from vCard4/hCard(2), why the above is a subset of vCard4/hCard(2). Some common reasons:

  • NU - Not commonly used in practice, either in address books or in publishing on the web. Reconsider such properties if usage changes.
  • ER - Error prone whenever entered/published. Such properties are toast. Not getting added.
  • AB - Absent from typical device address books (if you've seen a specific device with such fields in the address book, please list it here as a nested list item, preferably with screenshot of the UI). Reconsider such properties if added to address book UIs, note such research/data accordingly in #Considered_changes section below.

Specific deliberately omitted property notes:

  • 'logo' - NU, 'photo' is used instead
  • 'post-office-box' - NU, AB
  • 'extended-address' - ER. in practice such data typically ends up in a long 'street-address'.
  • 'organization-name' and 'organization-unit' are rarely separately specified, users/publishers preferring to use the simple flat 'org' property instead.

Added for B2G db (but not in any known existing device address books):

  • ContactAddress 'geo' property components 'latitude', 'longitude' and additional 'altitude' from GeoLocation API
  • Contact 'gender' property components 'sex', 'gender-identity' (from vCard4/hCard2 in particular)

Example

var contact = new mozContact();
mozContact.init({name: "Tom"}); // Bug 723206
var request = navigator.mozContacts.save(mozContact);
request.onsuccess = function() {alert("success");};
request.onerror = function() {alert("error")};

Considered changes

  • mozContacts object might move to window.navigator.device;
  • more Contact attributes (from Address Book UIs of BlackBerry (BB), iPhone/iTouch (iOS), MacOS Address Book (MOAB).
    • ringtone (BB, iOS)
    • messagetone (BB)
    • phonetic-given-name (iOS, MOAB) (2012-080 requested VCARDDAV)
    • phonetic-family-name (iOS, MOAB) (2012-080 requested VCARDDAV)
    • formal-name (per suggestion from Jonas), like name, but with all "honorable so and so" etc. included as you would formally address or introduce someone. needs examples of publication on the web, and/or device address books that actually include such a field (haven't seen one yet).
    • sort-string / sort-as. per suggestion from Jonas, the Japanese iPhone has a field for "phonetic last name" which can be used for sorting. The existing vCard3 sort-string property or vCard4 sort-as (sub)property could be used to capture this if the only intended use is sorting.
  • add interface ContactTelephone
    • change ContactProperties tel from "DOMString[]" to "ContactTelephone[]"
    • define a new "interface ContactTelephone" with
      • DOMString[] type; // or just DOMString type; and force multivalues to be comma delimited e.g. iOS "work fax" becomes "work,fax" for vCard compat.
      • DOMString number;
  • add type to interface ContactAddress:
    • DOMString[] type; // or just DOMString type; and force multivalues to be comma delimited e.g. "dom postal" becomes "dom,postal" for vCard compat.

FAQ

Why are givenName familyName arrays instead of optional

  • could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. givenName, familyName. Those seem like 0-or-1 cases, not lists.
    • i18n. Experience with vCard3 and hCard with international content has shown that multiple different languages/cultures have multiple given names and family names, and thus the change was made in vCard4 to make these multivalued. - Tantek 10:37, 25 October 2011 (PDT)

Why are flattened adr properties arrays instead of optional

  • could use clarification of why a number of fields are arrays instead of optional DOMString. e.g. fields of the flattened adr. Those seem like 0-or-1 cases, not lists.
    • Simplification and i18n. The multivalued adr properties are a result of both lack of use / common mis-use of post-office-box and extended-address properties (such data is more often/reliably shoved into multiple lines of street-address) and countries having multiple lines/values for street-address and/or locality/region. - Tantek 10:37, 25 October 2011 (PDT)

Is the name property a composition or something users enter

  • Is the name property a composition of given and family name or is it something users can enter?
    • The name property is 'fn' and can be entered. The 'name' property is the replacement for 'fn' (formatted name) from vCard/hCard. This is an explicit renaming (to 'name') that multiple parties have independently done (decentralized convergent evolution), and thus is being adopted in hCard 2 and thus we are adopting as well in the ContactsAPI. The 'name' property is something users can enter, DAP calls it 'displayName" or something needlessly divergent like that.

Why are abbreviations used for adr bday org tel

  • Why are abbreviations used for the 'adr', 'bday', 'org', and 'tel' properties?
    • property names re-used literally from vCard/hCard. 'adr', 'bday', 'org', and 'tel' are re-used with the same semantics from vCard and hCard (which itself is a well-established part of the web platform). It is better to re-use literal names of existing properties rather than re-name them in a good intentioned (but ill-wrought) attempt to "fix" names (for differing opinions/values of "fix"). This is a general design principle borne out of experience with earlier attempts at re-use/re-naming which resulted in unnecessary vocabulary divergence. See preserve literal vocabulary when reusing meaning.

Why re-use property names from vCard and hCard

  • Why re-use property names from vCard and hCard?
    • clarity, continuity, interoperability, avoiding divergence. Re-using names when re-using semantics from well established existing standards has the advantage of better consistency, clarity, understanding, continuity, interoperability, and perhaps most importantly, avoiding divergence, which is exactly what does happen (and has) when people re-name things, abbreviations or otherwise. See: avoid renaming when reusing and note the provided example of the failed/divergent efforts to rename the 'org' property in particular over the years.

What is impp

  • What is impp?
    • impp is defined by RFC 4770 and incorporated into vCard4. The 'impp' property is for specifying URLs for instant messaging and presence protocol communications associated with a contact.

Issues

permissions and privacy

iOS Apps had a major embarrassment with the disclosure that apps like Path were automatically uploading your address book to their servers. More here:

http://kottke.org/12/02/more-on-iphone-address-book-privacy

We need a permissions/privacy model for ContactsAPI that is better and reflects user expectations. For now we're going with a whitelist for implementation purposes.

This is an open issue and needs some UI/UX flows figured out from which we will add to the API accordingly.

W3C DAP Contacts

The DAP WG (W3C) has contacts specification [1] sharing some of the goals of this proposal.

[1] http://dev.w3.org/2009/dap/contacts/

For the moment, the Contacts API proposal differs from the DAP specification in some key ways:

  • The ContactsAPI is a simplified / flattened properties/interfaces/API per lessons learned with the development of both vCard4 and hCard (including hCard 2)
  • The ContactsAPI's read/write API is explicitly designed to avoid multi-access write corruption.

Both of the above are fairly significant fixes to major problems in the W3C DAP Contacts API.

There's also the W3C's wiki page on ContactsMozDapComparison but it is quite out of date. It would be good to update that page with the advantages / reasoning of this ContactsAPI.

Clients

Applications using the ContactsAPI:

Potential Clients

Articles

Articles mentioning / discussion the ContactsAPI:

Retrieved from "https://dev.wikimo.nonprod.webservices.mozgcp.net/index.php?title=WebAPI/ContactsAPI&oldid=421842"