[ACTION-373] Review Chris' changes to API document (done)

Dear all,

sorry again, but i have forgot one last comment on the API: Are you sure, that you can use WebService calls with call-by-reference e.g., in Java? I might be wrong, but i donīt think this is going to work because of (de-)serialization of the parameters.

Cheers,
Florian

Anfang der weitergeleiteten E-Mail:

> Umgeleitet von: public-media-annotation@w3.org
> Von: Florian Stegmaier <stegmai@dimis.fim.uni-passau.de>
> Datum: 5. Januar 2011 12:00:38 MEZ
> An: public-media-annotation@w3.org
> Betreff: [ACTION-373] Review Chris' changes to API document (done)
> 
> Dear all,
> 
> at first i want to wish you all the very best for the new year 2011! I hope you all had nice holidays!
> 
> The last two days, i found enough time to get into the new API document and to come up with some thoughts about it. At first i must admit that i was pretty confused in the beginning. This was more or less because of the Call-By-Reference definitions and the "strong" differentiation between sync and async. Nevertheless, i think Chris made a great work here, but we have to do a few changes to improve things.
> 
> I made several comments, more or less concentrating on the first sections. For me, the main issue is the description or better the explanation why we differ between sync and async like we do now - i tried to explain myself bellow. I also think, sync and async should be also reflected in the use case scenarios. So, i have attached my comments to the document below.
> 
> Cheers,
> Florian
> 
> ============================================================
> ============================================================
> = Notes on API for Media Resources 1.0 (W3C Editor's Draft 05 January 2011)
> ============================================================
> ============================================================
> 
> =====available at:
> http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html
> 
> ===========
> ===== Abstract
> ===========
> - "This specification defines a client-side API to..."
>    Delete "client-side". In section 2 we state, that this API can also be a WebService,
>    which is not located at the client.
> - "The overall purpose of this API is to provide developers with a convenient access
>    to metadata information stored in different metadata formats."
>    I think we should state, that the actual access to the metadata is not defined by us.
>    Only interfaces and the object structure of our pivot format. From my point of view,
>    the abstract a is is misleading.
> 
> ================
> ===== 1 Introduction
> ================
> - "This specification defines a client-side API..."
>    More or less the same issues as outlined for the abstract.
> - "This API serves as a mediator between a developer and the Ontology for Media Resources
>    1.0 [MEDIA-ANNOT-ONTOLOGY] with the goal of supporting interoperability between 
>    metadata formats."
>    Proposal:
>    This API defines/exposes interfaces that enables users/applications to consume metadata
>    in a interoperable manner. Here, interoperability between metadata formats is ensured by
>    the use of the Ontology for Media Resources 1.0 [MEDIA-ANNOT-ONTOLOGY] as pivot
>    metadata format.
> 
> =========================
> ===== 2 Design Considerations
> =========================
> - insert caption for Figure 1
> - Figure should be smaller and inserted before the sceanrio description
> - we now have sync and async modes of communication...should we reflect this also in the
>   scenarios? Maybe make a third one that cleary shows the need for an async call!
> - Bullet 3: clearly state here, that it is not part of our spec how the metadata access is done!
> 
> =========================
> ===== 3 Design Considerations
> =========================
> - "This API has a number of interfaces that represent media resources, media annotations,
>    and metadata sources, described using Web IDL."
>    This sentence carries no information. Proposal:
>    This API defines a number of interfaces that can be grouped in the following categories:
>        * interfaces defining the actual retrieval methods (GET) for metadata
>        * interfaces defining the structure of metadata objects/annotation
>        * interfaces defining the metadata source
>    These interfaces are specified by the use of WebIDL.
> - We should clearls state, that the API is mostly based on Call-By-Reference...this will improve
>    readability!
> - Why does the API description start with the description of the MediaResource interface?
>    Proposal:
>    Make a new Section 3.1 MediaResource interface, here we can put the general description
>    given in the beginning of Section 3. Make two subsection 3.1.1 Sync mode 3.1.2 async
>    mode.
> - 3.1: Change the ordering of the content. First come up with the WebIDL definition, afterwards
>    the example. Nevertheless, there is a example section with nearly the same example. Could
>    be also deleted here (would propose from "obtaining" until "media resource").
> - "Next, we give some JavaScript..."
>    wrong styling
> - 3.2 same remarks as for 3.1 since it is the same text. from my point of view, we have to state
>    how this implementation is different from sync mode...this has to be revised i guess
> - regarding sync and async: from my point of view, it is really valuable to have these two modes.
>    but now, we are a little bit weak from the point their differentiation. We have to discuss things
>    like "Why do i have to implement the sync mode? i could implement the async mode and fetch
>    immediately the answer!" So for guys like this, there would be only one mode serving both.
> - "Next, we give some..."
>    wrong styling
> - 3.2 i think all the callback things should be explained a little bit more...this part is confusing
> 
> ==============
> ===== Appendix A
> ==============
> - "DOMString getPropertyNamesHavingValues (DOMString[] propertyNames, ..."
>    missing "in"?

_____________________________
Dipl. Inf. Florian Stegmaier
Chair of Distributed Information Systems
University of Passau
Innstr. 43
94032 Passau

Room 248 ITZ

Tel.: +49 851 509 3063
Fax: +49 851 509 3062

stegmai@dimis.fim.uni-passau.de
https://www.dimis.fim.uni-passau.de/iris/
http://twitter.com/fstegmai
_____________________________

Received on Wednesday, 5 January 2011 11:56:23 UTC