Review of API for Media Resource 1.0

Hi,

this review is personal (i.e. neither as Vodafone nor DAP chair), and is based on the http://www.w3.org/TR/2010/WD-mediaont-api-1.0-20100309/ draft.

• Abstract: "The API will be introduced in an abstract manner", I don't think it's in the future (this is repeated later).

• Similar comments as made previously concerning the custom CSS (I have to disable that rule in Firebug to make the document readable).

• "It offers GET operations" Is this a statement of adherence to REST or simply an indication that access is read-only?

• Typos: "addtion", "unstructeredValue", "uri's" -> "URIs", "determins"

• What is a MAObject, what does it represent? It's very hard to understand what the field mean without a clearer definition. Is it just intended as a base class for all media annotations? Wouldn't calling it MediaAnnotation be clearer than MAObject?

• I find the usage that is made of WebIDL and corresponding descriptions hard to read. There are tools like ReSpec, Anolis, and others that make generating clear and marked up WebIDL easy; they might be worth investigating. (Compare with how interfaces are defined in any DAP draft, or in the File API for instance.)

• The description says that MAObject has a language attribute, but it's really on Language.

• I am guessing that the attributes of MAObject have constraints beyond just being DOMStrings, but they don't appear to be specified.

• All the MAObject attributes are created as read-write, but it seems unclear what happens on setting.

• The text about the two implementation scenarios seems out of place — what is its relationship with the WebIDL above? Isn't it introductory? The second scenario contradicts earlier statements according to which this is a client API, and confuses me as to the exact scope of the specification — is it not just intended as a JS API to get metadata out of documents?

• I personally don't see what the two diagrams add in terms of comprehension — if anything, it should go into the text. My personal recommendation would be to remove them but if the WG decides to keep them they should probably be converted to an accessible graphics format such as SVG so that the text that they contain can be read, enlarged, searched, etc.

• 2.2: I don't understand the first paragraph at all, and following that I don't understand what interface setContent() is on.

• MetadataSource seems to be created in passing, without much explanation as to what it really means.

• Similarly, I don't understand section 2.3, or where getProperty() is meant to be. All I can surmise is that it must be getting a property, somehow, on something, and that it seems more complicated than I like methods to be, but maybe that's just a feeling because I don't see what it does.

• In addition to more detail in the descriptions, examples would help. For instance, converting Mozilla's File API + EXIF parser to your API might be interesting.

• I don't understand the examples for "identifier". In fact I don't understand the whole section. It says that it implements the StringObject interface, but StringObject just has a "value" field and Identifier also has a "value" field — and it doesn't inherit from StringObject but from MAObject. The example then goes on to list an array of one string, when one would expect (from the description) an array of object literals containing the fields defined on Identifier and inherited from MAObject. The usage as a service then makes it more confusing. And it's not clear what interface the identifier attribute (is it that?) is on.

• Pretty much the same comments apply to all the other properties.

• Title: Why just "Album title" and "Song title"? A *lot* of other things can have titles.

• What is the relationship between language in 2.3.1.3, and the Language interface? Why is the StringObject defined here and what is it meant to do?

• I skipped over all the other properties because I simply cannot understand enough of their description to review the document. I am sorry, I don't intend to be mean, but I find this document to be mostly incomprehensible. How about starting with several examples and modelling the WebIDL sections on existing specifications?

• "API for retrieval of reason of an error" Is there a reason to use this approach instead of an error callback or an exception? Note that what getDiagnosis() is supposed to be called on is unclear.

• Long names like getPropertyNamesWithValues() and getSourceFormatsWithValues() are unpopular and for good reason. This isn't supposed to be a Java API!

• The XML examples in 2.5.3 use xsi:schemaLocation, which is very probably an XML bad practice and certainly best avoided in an example.

• There are serious security concerns with this API, notably in terms of privacy as geo data can be exposed alongside time, which is a great way of tracking someone.

• Appendix A loses me yet again, it seems to be saying something different from the previous sections.

• The interfaces aren't clear as to whether they have constructors, in what scope, etc.

• There are pretty much no conformance clauses, normative statements, testable assertions, etc. This is a concrete API, it must be testable.

With respect, this document is not at all ready for LC. As a first step I recommend devising a few examples that cover the API's intended usage, and then taking inspiration from existing API specifications in terms of how to describe WebIDL, then redoing a review to see where it's at.

Best of luck!

--
Robin Berjon
 robineko — hired gun, higher standards
 http://robineko.com/

Received on Tuesday, 23 March 2010 15:42:17 UTC