ACTION-159: review of API document

Dear all,

I have reviewed the current draft of the API document. It is acceptable as a first draft, giving and outline of what the API will be, but clearly there are still many open issues. Here are my comments:

* Section 1 Introduction
- I think one or two sentences could be added to the introdcution stating that many issues are open and that some of the definitions are provisional.
- The sentence "The initial version of this document is not a final version." should be dropped, I think that's obvious.
- while section 2 says only read access is defined, the introduction still says the API defines GET and SET operations
- I'm not sure if section 1.1 and 1.2 should be kept, the prefixes are not used in the document, so I think a reference to the ontology document for the formats in/out of scope is sufficient.

* Section 2 API Description
- It could be useful to put the first paragraph (which is long and could be split) into a section called e.g. "design considerations".
- I suggest to move the WebIDL of the complete API after the description of the getters or even into an annex.
- as mentioned in my earlier comments to the list, it is not clear to me why some getters only return a single value (e.g. title), especially if there are qualifiers for subtypes/roles. 
- identifier example: I think it would be useful to use an example that is different from the locator to make this difference clear.
- list of role/subtype identifiers: should we add the preliminary definitions we have to a section in the API document instead of linking to the MAWG wiki?
- several property definitions mention resource and explain that it can be an abstract concept or an instance. It think we should reference section 2 of the ontology document in the introduction and drop this explanation from each of the property descriptions
- 2.1.5.2 license / statement attribute: is this really free text? Shouldn't this be "creativecommons.org/licenses/by/2.5" in the example?  

Minor issues:
- web is sometimes written with uppercase W and sometimes not
- in the intro paragraph of 2, change "unStructured" -> "Unstructured"
- title example (2.1.1.2): could be a bit nicer, e.g. spaces instead of dashes
- 2.1.2.2 return type: Array -> array
- 2.1.3 I suggest to drop "description" from the title 
- 2.1.7.1/2.1.7.2 there is a space missing between "an array of" and "object"
- section C: the list of members should be updated (e.g. Florian is missing, my affiliation is outdated)
- MPEG-21 reference spells MPGE and the rest is missing

Best regards,
Werner

--------------------------------------------------------------------
  Werner Bailer
  Institute of Information Systems
  JOANNEUM RESEARCH Forschungsgesellschaft mbH
  Steyrergasse 17, A-8010 Graz, AUSTRIA
 
  phone:  +43-316-876-1218               mobile: +43-699-1876-1218
  web:    http://www.joanneum.at/iis        fax: +43-316-876-1191      
  e-mail: mailto:werner.bailer@joanneum.at
--------------------------------------------------------------------

Received on Thursday, 8 October 2009 14:30:24 UTC