RE: [contacts] Comments on editors draft of Contacts API

Hi Dom,

Thanks for the review. I've included some responses below.

I welcome further review of this API [1] from other DAP participants. 

Richard

On 30th Nov 2009 10:21, Dominique Hazael-Massieux [dom@w3.org] wrote:
> Hi Rich,
> 
> Here come a few comments on the current editors draft [1] of 
> the Contacts API; I think the questions are likely to apply 
> to other APIs in the future, so hopefully looking at them now 
> will help for later too.
> 
> * all the interfaces defined in the API are annotated with 
> [NoInterfaceObject] [2] ; I think it's may make sense for the 
> Contacts interface depending on the mechanism used to secure 
> the access to the addressbooks, it's probably not appropriate 
> for many of the other interfaces; for instance, I don't see 
> how one would add a contact right now, since one cannot 
> instantiate the Contact interface; was there a rationale for 
> hiding the interface object? Maybe some of the interfaces 
> can/should remain hidden through convenience functions, but 
> they're not defined in the API right now

I picked this up and the latest draft deals in both [NoInterfaceObject]
and [Constructor(..)] as appropriate.

> 
> * assuming the Contact interface becomes instantiable, it 
> would probably need a constructor with a non-optional 
> formatted name parameter?
> 

Contact does become instantiable in the latest Contacts draft.

> * should there be convenience-functions to add/remove 
> elements to the sequence properties in Contact that are more 
> than just DOMString?

This is a good idea. Rather than having to deal directly with nested
array and object literals it would be easier to expose convenience
functions to developers.

I will include this in the next draft of the specification.

> 
> * I think all the attributes in Contact but "name" should be 
> annotated with a "?" since they are optional [3]; likewise, 
> all the attributes in ContactName should be marked with "?" 
> but "formatted"
> 

In the latest draft of the API the attributes of Contact have been
abstracted out to ContactProperties (in a move for the new
ContactProperties to also replace the previously included ContactFilter
interface).

When a Contact object is instantiated, ALL attributes supported by the
current implementation MUST be provided in the resulting Contact object
-> a developer can then enumerate over the resulting objects to see
which attributes are supported or not in the current implementation (and
therefore whether it is necessary to set/get these attributes).

To represent this, I've placed a description to this effect in the
Contact interface section. When the ContactProperties are used as a
filter to a find() method, then the strict provision of these attributes
in the filter object is not necessary.

So rather than annotate with a "?" I've chosen to directly express the
optionality of all components in the related interface descriptions.

Does this work?

> * I think the ContactAddress interface should mark as an 
> editors note or as an issue the possible relation to the work 
> in Geolocation v2:
> http://dev.w3.org/geo/api/spec-source-v2.html#address_interface
> I think we'll want to converge with it over time; note that 
> they define it as read-only since in their case they exchange 
> immutable objects, but we would clearly need a mutable one 
> [side note: I wonder if that's something that would be better 
> defined as property of a specific instance rather than 
> hardcoded in the interface, but I don't think WebIDL allows 
> for this currently]
> 

Added to the latest draft specification.

> * I am a bit nervous about using SQL as the formal language 
> to describe the filtering algorithm; I think given that the 
> filtering we're doing is rather simple (OR / AND / LIMIT / 
> OFFSET), I would go with a prose or mathematical description 
> on the set of known contacts.
> 

I'm not particularly pleased with the 'Contact Search Processing Rules'
section for this reason. This is currently highlighted as an editor's
note. Perhaps you have some examples on which I could draw to rework
this section?

> 
> 1. http://dev.w3.org/2009/dap/contacts/
> More specifically, v1.13
> http://dev.w3.org/cvsweb/~checkout~/2009/dap/contacts/Overview
> .html?rev=1.13&content-type=text/html;%20charset=utf-8
> 2. http://dev.w3.org/2006/webapi/WebIDL/#NoInterfaceObject
> 3. http://dev.w3.org/2006/webapi/WebIDL/#idl-nullable-type
> 
> 

Thanks,

Richard

Received on Monday, 30 November 2009 17:05:52 UTC