Re: Status of the API Doc v1.0

Dear all,

I think this initial draft is a good starting point. But there are a  
few major things, i am wondering about:

a) what about using interfaces as Victor proposed in [1]?
b) did we choose one of the two possibilities for the API already  
(specific vs. common)? AFAIK only a few of us discussed these two  
different approaches [2].
c) the datatypes are only "placeholder" for the finite datatypes, or?  
Because some of them do not fit their purpose i guess.
d) as Victor already pointed out, WebIDL is in scope of our group, so  
we should bring this discussion to an end and use it...

I think we have to discuss this draft more closely in todays telecon.

Best,
Florian

[1] http://lists.w3.org/Archives/Public/public-media-annotation/2009Aug/0007.html
[2] http://lists.w3.org/Archives/Public/public-media-annotation/2009Sep/0023.html

Am 15.09.2009 um 07:33 schrieb 이원석:

> Hi. Co-editors.
>
> Below is initial contents for API description part of API doc, even  
> it’s not described by Web IDL. It could be covered later.
> Structure of this is just following the order of properties in the  
> summary table[1].
>
> If you have any comment or question, please let me know.
> How about structure of API description clause, categorization of  
> API ???
> In addition, we have to take more parameters for API into account.  
> Do you have ideas ?
>
>
> 3. API description
>
> 3.1 API for Descriptive Properties
>
> 3.1.1 Identification Properties Interface
> String ma_getIdentifier();
> String ma_getTitle();
> String ma_getLanguage();
> String ma_getLocator();
>
> RESULT ma_setIdentifier(String id);
> RESULT ma_setTitle(String title);
> RESULT ma_setLanguage(String lang);
> RESULT ma_setLocator(String loc);
>
> 3.1.2 Creation Properties Interface
> List<String> ma_getContributor();
> List<String> ma_getCreator();
> Date ma_getCreateDate();
> String ma_getLocation();
>
> RESULT ma_setContributor(List<String>contributor);
> RESULT ma_setCreator(List<String> creator);
> RESULT ma_setCreateDate(Date createDate);
> RESULT ma_setLocation(String loc);
>
> 3.1.3 Content description Properties Interface
> String ma_getDescription();
> List<String> ma_getKeyword();
> String ma_getGenre();
> String ma_getRating();
>
> RESULT ma_setDescription(String desc)
> RESULT ma_setKeyword(List<String>keyword)
> RESULT ma_setGenre(String genre)
> RESULT ma_setRating(String rating)
>
> 3.1.4 Relational Properties Interface
> String ma_getRelation();
> String ma_getCollection();
>
> RESULT ma_setRelation(String relation);
> RESULT ma_setCollection(String collection);
>
> 3.1.5 Rights Properties Interface
> String ma_getCopyright();
> String ma_getLicense();
>
> RESULT ma_setCopyright(String copyright);
> RESULT ma_setLicense(String license);
>
> 3.1.6 Distribution Properties Interface
> List<String> ma_getPublisher();
> String ma_getTargetAudience();
>
> RESULT ma_setPublisher(List<String> publisher);
> RESULT ma_setTargetAudience(String targetaudi);
>
> 3.1.7 Fragments Properties Interface
> List<String> ma_getFragments();
> List<String> ma_getamedFragments();
>
> RESULT ma_getFragments(List<String> frags);
> RESULT ma_getnamedFragments(List<String> namedfrags);
>
>
> 3.2 API for Technical Properties
>
> Dimension ma_getFrameSize();
> int ma_getCompression();
> int ma_getDuration();
> String ma_getFormat();
> int ma_getSamplingrate();
> int ma_getFramerate();
> int ma_getBitrate();
> int ma_getNumTracks();
>
> RESULT ma_setFrameSize(Dimension framesize);
> RESULT ma_getCompression(int compression);
> RESULT ma_getDuration(int duration);
> RESULT ma_getFormat(String format);
> RESULT ma_getSamplingrate(int samplingrate);
> RESULT ma_getFramerate(int framerate);
> RESULT ma_getBitrate(int bitrate);
> RESULT ma_getNumTracks(int numtracks);
>
>
> 3.3 API for Iterating operation ???
>
>
> [1] http://www.w3.org/2008/WebVideo/Annotations/drafts/ontology10/WD/summary.html
>
> Best regards,
> Wonsuk.
>
>
> From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org 
> ] On Behalf Of Chris Poppe
> Sent: Tuesday, September 08, 2009 6:37 PM
> To: public-media-annotation@w3.org
> Subject: RE: Status of the API Doc v1.0
>
> Dear all,
>
> I have  been thinking a bit on the API-document, more specifically  
> on the content. As I see it, it would make more sense to put section  
> 4 (API description) before section 3 (Data type description). Hence  
> the document would have following structure (I also give a brief  
> description of each section as how I would see the API document):
>
> 1.       Abstract
> 2.       Introduction: reason why we want to provide an API and an  
> explanation on who should use/implement it.
> 3.       API description: a precise description of the actual  
> methods in the API, (so these are the methods that can be found in  
> the Strawman API design [1]), described using web IDL. Victor has  
> already sent an excellent example (using IDL). This section needs to  
> define and explain all aspects of those methods (parameters and  
> return values).
> 4.       Data type description: Here we discuss for each property in  
> the ontology what the specific return values are.  (for example if  
> we call the GetStructuredValue method for property ma:creator, what  
> would be the structure and content of the result (so in fact a kind  
> of Javadoc style)). The examples that were added to the summary  
> table [2] are an obvious starting point and should also be repeated  
> in this section to clarify what is meant.
> 5.       Examples of how to use the API: Here I think we should  
> discuss actual (working) implementations that implement this API.
>
> Not everything has been decided upon (which methods, return values,  
> etc. ). However, the document will be a good (imo better) starting  
> point for further discussions on this topic. I also believe that it  
> might be difficult to use the paper that is currently being written  
> as a first version of the API doc. Presumably, only the introduction  
> can benefit from the paper but the contents of the paper is actually  
> more on the ontology and ways to define the mappings.
>
> I would happily volunteer in sections 3 and 4 but I would like to go  
> through the web IDL specification first.
>
>
> [1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes
> [2] http://www.w3.org/2008/WebVideo/Annotations/drafts/ontology10/WD/summary.html
>
> Kind regards,
> Chris
>
>
>
> From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org 
> ] On Behalf Of ???
> Sent: dinsdag 1 september 2009 4:27
> To: Florian Stegmaier; Victor Rodriguez Doncel; Chris Poppe
> Cc: public-media-annotation@w3.org; ???
> Subject: RE: Status of the API Doc v1.0
>
> Dear Florian and All,
> We are just in the starting point for preparing API doc because of  
> vacation season.
> So, It’s time to hardly work for reaching to our goal. ;) I think  
> we have to make early version of first draft until 15th September.
>
> Below is the structure we had and I describe proposal how to  
> describe each part. If anyone have better ideas, please let me know.
> In addition, I am looking for volunteers for each part. Please let  
> me know.
>
> 0.     abstract à need to make first draft
> 1.     Introduction à need to make first draft
> 2.     Terminology à firstly add the terms from ontology doc if we  
> need. And then add additional terms if we need.
> 3.     Data type Description à Do anyone have ideas ?
> 4.     API Description à After referred Strawman API design and  
> notes page[1] in wiki, describe draft APIs based on the core  
> properties of ontology doc.
> 5.     Examples of how to use the API(in Java for example(chris),  
> web IDL) à I think it could be covered later after mature of APIs.
>
> [1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes
>
>
> Best regards,
> Wonsuk
>
> From: Florian Stegmaier [mailto:stegmai@dimis.fim.uni-passau.de]
> Sent: Monday, August 31, 2009 11:33 PM
> To: 이원석; Victor Rodriguez Doncel; Chris Poppe
> Cc: public-media-annotation@w3.org
> Subject: Status of the API Doc v1.0
>
> Dear all!
>
> I wanted to know, if there is already a progress on the API Doc v1.0?
>
> Should we start working on the outline proposal of Wonsuk? Who will  
> be in charge of coordination and the yet defined parts?
>
> I think we should keep in mind, that the first deadline is preety  
> near (early October) and we should initiate the work on it asap.
>
> Best,
> Florian
>
> _____________________________
> 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
> _____________________________
> Quote of the week: Computer. This is a Class-A compulsory directive.  
> Compute, to the last digit, the value of pi. (Spock)
>
>
>
>
>
>


_____________________________
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
_____________________________
Quote of the week: Computer. This is a Class-A compulsory directive.  
Compute, to the last digit, the value of pi. (Spock)