RE: ACTION-19 contact api review / feedback

On 14th Oct, 2009, at 11.11, Anssi Kostiainen wrote:
> On 13.10.2009, at 19.21, ext wrote:
> >>
> >> On 9.10.2009, at 17.12, ext 
> wrote:
> >>
> >> The find method should perhaps be described as something like 
> >> (reflecting the latest Contacts API ED):
> >>
> >> sequence<Contact> find (in sequence<ContactFilter> filters);
> >>
> > Suggesting Object was to allow for one ContactFilter to be 
> passed OR a 
> > sequence of ContactFilter objects to be passed, effectively 
> allowing 
> > represention of 1 or n ContactFilters. Having said that, 
> your proposal 
> > is simpler and consistent, though an Array object will always be 
> > required, even for just a single ContactFilter object. I 
> should have 
> > explained the rational for Object in my original email. I can live 
> > with either proposal.
> I reflected this issue against jQuery API [1] which is 
> considered intuitive by many developers and it seems many of 
> its methods* use overloading similar to your proposal. Thus 
> it seems justifiable to also support passing one 
> ContactFilter object directly to the find method w/o forcing 
> the object to be wrapped into an Array (albeit that's also 
> supported). 

Great. I was also checking against general Javascript conventions and
was primarily using jQuery as my reference on good practice, hence the
proposal to overload find(...).

> This leads us to the following interface 
> definition for the overloaded find method:
> sequence<Contact> find (in ContactFilter filter); 
> sequence<Contact> find (in sequence<ContactFilter> filters);

This looks right (plus we need to add the optional ContactFilterOptions
discussed previously in this thread to allow for pagination of contact
results - see below for the 'takeaway').

Do we need to be more specific in the specification on whether the
ContactFilter matching is strict or loose? i.e. if I search for
name='Rich' will it return (where name=Rich AND where name=Richard)
[loose matching] OR just an exact match (where name=Rich) [strict
matching]? I'd prefer to specify loose matching if we need to say
something on this.

This proposal is an additive search model. We are missing NAND and NOR
from the logic. I'd be interested if this is a significant limitation of
the proposal or whether we've struck the right balance initially between
simiplicity and flexibility of contact searching - considering that most
common searches are additive (AND/OR) rather than subtractive

> (The argument passing convention discussed herein is related 
> to the ISSUE-1. We could take a look at the other established 
> JavaScript libraries as well for more extensive analysis if 
> that's seen beneficial by the group.)

My takeaway from this thread is to add the following to our umbrella
requirements [1], Section 8:

- MUST provide options to enable the pagination of contact search

And we should add the following to the current Contact API proposal [2]: Section 3:

     A description of the AND/OR model in use (with possible example) +
addition of optional ContactFilterOptions parameter

     The following WebIDL clarification:

     sequence<Contact> find (in ContactFilter filter, [Optional] in
ContactFilterOptions options); 
     sequence<Contact> find (in sequence<ContactFilter> filters,
[Optional] in ContactFilterOptions options); Section 3.1:

     Description of additional method added in Section 3 (above). Section 4:

     Addition of a 'category' attribute to allow for CRUDing of groups
of contacts Section 4.1:

     Description of additional attribute (category) added in Section 4
(above) a new Section: ContactFilterOptions interface (+ a subsection
describing the attributes therein)

     interface ContactFilterOptions {
             attribute int limit;
             attribute int page;

What I still see outstanding in the discussion are the finalisation of
the attributes that have been provisioned in the Contact interface [3].
This discussion has been started on the mailing list but has not yet
been resolved:



I'm happy to jump in to the editing of the Contact API specification
myself as required considering the load on other contributors.

br/ Richard




Received on Wednesday, 14 October 2009 11:51:46 UTC