Re: Contacts API draft

Hi Eduardo,

Thanks for taking a look and highlighting the differences.

On Wed, Nov 7, 2012 at 11:03 AM, EDUARDO FULLEA CARRERA <efc@tid.es> wrote:

>  Hi Christophe, all,
>
>
>
> I have been comparing the two proposals on the table for Contacts API, and
> they happen to have more similarities than differences what is good news in
> order to reach a consolidated proposal. Let me comment on the main
> differences:
>
>
>
> -Filtering: Intel’s proposal allows applying virtually any type of filter
> as it allows the definition of composite filters. Note though that in order
> to have an appropriate performance the runtime will need to define indexes
> for the different filtering operations. Having so flexible filtering
> implies creating a virtually unlimited set of indexes. Christophe, what is
> the performance you expect the implementation to have? and how do you
> propose to solve that issue?
>

Well, it is a good idea for the backend to define indexes to make the
common filtering operations faster. I fail to see the relation between
having a flexible filtering system and creating a virtually unlimited set
of indexes.
In my opinion, just because the backend cannot optimize for all possible
queries does not mean that we should restrict which queries are supported
by the API.

If you consider SQL, you can query pretty much anything even if some of
these queries may be slow. All we can do is define indexes in the database
to optimize the most frequent/common queries.
I think the same thing applies here. The addressbook is basically a layer
on top of the database and the filtering system is merely a layer on top of
whatever query language is being used by the backend (e.g. SQL).

Also note that if we don't provide flexible filtering then this means that
the app will likely need to do post-filtering by itself on JavaScript side.
I believe that even if the native backend is not optimized for all queries,
those are still going to be faster compared to the alternative
(post-filtering on JS side).


>
>
> -ContactChangeEvent: Intel's proposal allows notifying changes in multiple
> contacts simultaneously indicating which contacts have been deleted,
> created and modified. Is the system expected to wait for some time before
> firing an event with multiple changes or do these notifications of multiple
> changes apply just to really simultaneous changes (e.g. sync with an
> external address book).
>

We were thinking about database transactions in the backend. For those, I
think it is a good idea to return all the changes in the same event, this
is better for performance that firing one event per change.
The idea is also to have a generic ContactChange event which handles all
possible Addressbook changes in one object.


>
>
> -getSimContacts(): Our proposal included this method to be able to
> retrieve the contacts from the SIM card (e.g. to copy them to the device
> address book). It is not the intention to deal in any other way with the
> SIM’s address book, so neither the rest of the methods (find, remove, etc)
> nor the ContactChangeEvent apply in principle to SIM contacts.
>

We removed this method because it seemed too specific. The device may not
have a SIM card and I did not understand why we needed to handle SIM
contacts any differently at API level.
I don't have strong feeling about this one but I thought that the
Contact.readonly flag would allow us to achieve the same thing (Contacts
can be retrieved from SIM using find() but cannot be removed or saved
because they are marked as 'readOnly').


>
>
> -read-only contacts in Intel’s proposal: Christophe, could you elaborate
> what is the use case for that?
>

In some cases, the backend is not able to edit specific contacts. It can be
useful for SIM contacts for example. In case we are only able to read
those, not edit them.
It can also be useful for contacts coming from online services which may
not support editing.


>
>
> -Additional fields in Intel's proposal: relationship, phoneticGivenName;
> phoneticFamilyName; favorite; ringtone
>

Yes, we introduced those attributes because we had them in Tizen and they
are common vCard extensions. They also have practical use cases for the
AddressBook application.


> -Additional fields in our proposal: genderIdentity; carrier attribute in
> tel field
>

Yes,
- GenderIdentity is part of vCard 4.0 but we could not find much use for it
(we already have "gender" attribute).
- carrier is not part of the vCard standard AFAIK and seemed very specific.
we were not sure this should be part of the standard API. The application
could easily handle this by itself if needed.


>
> Any other relevant difference that I am missing?
>

A few:
- We did not use abbreviations in the attribute names because it decreases
readability. I know that yours match what is in vCard format but I don't
think readability is an important issue for vCards since they are processed
programmatically. For example, the abbreviation "adr" for an "address" is
not very good in my opinion.
- We changed the types of some attributes. We did not use array types for
name attributes (other than nickname). I know the vCard format supports
this but I don't know how useful it is and it makes the API a bit more
convenient to use.
- We use a partial interface for the Navigator extension as advised by [1].


[1] http://darobin.github.com/api-design-cookbook/

Kr,
-- 
Christophe Dumez
Linux Software Engineer, PhD
Intel Finland Oy - Open Source Technology Center