ACTION-143 - Feedback on the Gallery API

Hi,

Here's my feedback on the Gallery API (18 March 2010 version) [1]. Overall, I feel this early draft could be still simplified to make the highest value use case (retrieving a list of media items) simpler. More advanced stuff could be pushed to v2. It might also be beneficial to align its design more closely with the other similar (DAP) APIs. Some details below.

* Galleries interface

- I'd drop the Galleries interface from v1 and work with a single gallery instead, similarly to abstracted contact sources of Contacts API. The concept of multiple galleries could be baked into find()'s filter (see below) if needed.

* Gallery interface

- Using string constants would be better for readability, "desc", "asc" etc. However, it seems WebIDL does not allow that, there's some related discussion at [2]. I'm wondering whether there's a way around this WebIDL limitation that could also influence the design of other APIs (also outside of this WG)?

- If we drop Galleries interface we could also drop metadata attribute (and GalleryProperties interface) from v1.

- Instead of getNumofMediaObjects() I'd use a read-only attribute length.

-  I'd merge open(), close(), changeView(), getMediaObjects() and getMediaObject() into a single async method call find() similar to Contacts API. Include "fields" if minimization is seen important for this API as well, example:

  // find(fields, success, error, options);
  foo.media.find(['filename'], 
                 function(media) {},
                 function(err) {},
                 { /* options */ });

(media is an array of MediaObjects or an iterator to be REST-friendly with pagination, err is an instance of GalleryError and options of ViewType, aka MediaFindOptions below.)

- I'd drop refresh() as it seems like an implementation details that should not be exposed without a good use case.

- The simplified Gallery interface would thus look something like:

  [NoInterfaceObject]
  interface Gallery {
    const unsigned short MEDIA_SORT_NONE = 0;
    // + the rest of the constants
    readonly attribute unsigned long length;
    PendingOp find (in DOMString[] fields,
                    in MediaFindSuccessCB successCB,
                    in optional MediaErrorCB? errorCB,
                    in optional MediaFindOptions? options);
  };

* Other

- Perhaps s/Gallery/Media/g?

- For the rest of the requirements not yet covered, e.g. add, update and delete media items. The high-level API design of the Contacts could be followed where applicable as it seems fairly similar to this one. IMHO it makes sense to re-use the wisdom poured into designing and prototyping Contacts.

[I'm afraid I'm not able to review "API for Media Resource 1.0" and "Ontology for Media Resource 1.0" [3] in time. If someone else is planning to look at them feel free to chime in!]

This should close ACTION-143.

-Anssi

[1] http://dev.w3.org/2009/dap/gallery/
[2] http://www.w3.org/mid/m24owaci91.fsf@pc214.sm.oslo.opera.com
[3] http://www.w3.org/mid/4C0F413F.5080105@w3.org

Received on Tuesday, 6 July 2010 13:37:19 UTC