WebContacts API musings

[Philipp von Weitershausen]

I've been looking at the WebContacts API proposals by the W3C [1] and
WAC [2] while trying to write an all-web-tech implementation using
IndexedDB [3]. A few musings on the navigator.contacts API:

* The W3C API doesn't define easy methods for programmatically adding
and manipulating contacts. The vcard roundtrip it suggests for these
use cases isn't terribly useful for, say, an addressbook application
that wants to manipulate the data heavily. The WAC API otoh does
define methods for those usecases, so I've adapted them for my
prototype.

* I see the following use cases for getting data out of the contacts database:

(a) Get a list of all contacts (e.g. in an addressbook application)

(b) Get a list of contacts matching a particular search string.
Pretty much all applications (phone, SMS, email, maps, etc.)
auto-complete from the user's contacts when typing into the "To:" or
equivalent field. I think it's worth pointing out that the searching
should probably happen over multiple fields: in the phone and SMS apps
it would make sense to search over the display name (typically first +
last name) and the phone number fields, in the email app you
definitely want to autocomplete based on email addresses too, and in
the maps app it's the address...

(c) Get specific or all info for a particular contact based on an
identifier. This would be used in various apps when converting "opaque
identifiers" such as email addresses and phone numbers to real names.
The API should probably also do some normalization here. Email
addresses are case insensitive, phone numbers have various formats and
can be broken up with spaces and dashes, etc.

* The W3C and WAC APIs cover (a) very well. For (b) and (c), the W3C
API has this to offer in the ContactFindOptions interface:

filter of type DOMString, nullable
A string-based search filter which provides a hint to the user
agent to facilitate contacts selection by the user.

I can easily see how (b) could be covered (in a crude way) with this
if `filter` was just a search string. But how would (c) be covered? I
suppose we could invent some sort of query language, e.g.
"email=phil...@mozilla.com" or "phone=+15552341294" or maybe make the
filter an object as suggested by the WAC API, e.g. {email:
"phil...@mozilla.com"}. Whatever it is, this should be in the spec
because (b) and (c) are important use cases IMHO. ("The actual usage
of this search filter is user-agent dependant" as stated by the W3C
draft isn't very helpful...)

* The WAC API defines a ContactFilter object which allows one to
filter on different attributes. This easily covers (c). It also allows
for wildcarding via the % character. One could use this to build (b)
with this, but it's kind of awkward (one would have to union the
various possible queries). It feels like to me that a dedicated full
text search API (even if it's just simply passing in a string for the
filter, or defining a special attribute on the ContactFilter object)
would go a long way of API usability.

* The W3C API requires one to pass in "search qualifiers" when
retrieving Contact objects. This name is a bit misleading. They are a
whitelist of field names that will be present on the Contact objects
that are returned. That way the application explicitly requests only
the subset of fields on each contact that it needs. I can see the use
from a privacy perspective if we had fine-grained permission controls
("app wants to see your contacts' email addresses" versus "app wants
to know where your contacts live"). But this feels incredibly
complicated. From a technical perspective, one may be able to save a
few JOINs in the database (in theory at least), but other than that I
don't see much penalty in returning the full Contact object.

Thoughts?


[1] http://w3c-test.org/dap/contacts/
[2] http://specs.wacapps.net/2.0/jun2011/deviceapis/contact.html
[3] https://github.com/philikon/webcontacts (beware, it's rough)