RE: Feedback about the current API design

Hi Hui & Chris.

I added inline comments as below

 

From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org] On Behalf Of Lawrence Miao
Sent: Tuesday, September 22, 2009 10:38 PM
To: Chris.Poppe@ugent.be
Cc: public-media-annotation@w3.org
Subject: Re: Feedback about the current API design

 

Dear Chris

 

Thanks for the quick reply. 

 

About the issue we discussed in today's teleconf, I think strong type is better since the Web IDL style API will be binded to concrete languages. The strong type attribute (like first name, last name), I don't think its necessary. However, if we want to insist that some DOMString attribute contains a url, probably we need to define a URL type or find some way to solve it. 

 

I think URL type could be considered for the structured type.

 

Another question, does our API support create, update, or delete these kinds of operations? Or it's aimed to provide resource vocabularies only here?

 

I am not sure I understood rightly about your question.

Anyway I could say, so far we consider get and set operation. but I think the set operation could cover create, update even delete operation.

Therefore we should make clear the scope of set operation in the near future.

 

Best regards,

Wonsuk

 

Sorry that due to the company assignment, I missed some discussions in this working group. 

 

Best Regards, 

 

Hui Miao

 

On Tue, Sep 22, 2009 at 10:08 PM, Chris Poppe <Chris.Poppe@ugent.be> wrote:

Dear Lawrence, all,

 

I already answered to you personally on the questions you had, but I will repeat them here so everybody can see them.

 

As for the exception remarks, I agree that error codes can also be used. And probably are more interesting (for language issues and such). Currently we have not discussed (at all) what kind of exceptions should be raised so this was just a first step.

 

For the arrays I use, I have based myself on a W3C Editor’s draft from 30 august 2009 (http://dev.w3.org/2006/webapi/WebIDL/) which does include arrays in such ways.

 

Finally, the inheritance of the unstructured interface is included because we want to allow the possibility that the return value is in fact an unstructured string (for example if we don’t know what the first and last name is of a  creator, we might return an unstructured string containing both. In that case it is up to the application to parse the unstructured value.)

 

Kind regards,

Chris 

 

 

From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org] On Behalf Of Lawrence Miao
Sent: dinsdag 22 september 2009 13:48
To: public-media-annotation@w3.org
Subject: Feedback about the current API design

 

Dear All

 

I've sent feedback to the co-editors already. As requested, I summarized the feedback here. 

 

1. About the RESULT design

* Chri's has an approach by defining each type of Error as an interface with a string member denoting the error message. 
* I proposed another two approaches: First one, use the [ExceptionConstant] extend attribute documented at Web IDL specs [1] section 3.8.3. The [ExceptionConstant] is created to help documenting error code like exceptions. Here's the example:
 [ExceptionConsts=FileIOExceptioin]
 module fileio {
     exception FileIOException {
         unsigned short code;
     }
 
    const unsigned short FILE_NOT_FOUND = 1;
    const unsigned short READ_ERROR = 2;
    const unsinged short WRITE_ERROR = 3;
 }
* The second approach is refering BONDI [2] which is a Web IDL based API sepcification for web runtime applications. In BONDI, the exceptions are documented as normal 'interface' other than 'exception', as Web IDL 'exception' does not support inheritance. In the design pattern document of BONDI [3],  it contains the purpose behind their design. Here's the example:
 interface GenericError {    
      readonly attribute unsigned short code; 
 }; 
 
 interface DeviceAPIError : GenericError {    
      const unsigned short UNKNOWN_ERROR           = 10000;    
      const unsigned short INVALID_ARGUMENT_ERROR  = 10001;
      const unsigned short NOT_FOUND_ERROR         = 10002;    
      const unsigned short PENDING_OPERATION_ERROR = 10003;    
      const unsigned short IO_ERROR                = 10004;
      const unsigned short NOT_SUPPORTED_ERROR     = 10005;
 };

2. About the array type:

* As I know, the way to define an array in Web IDL is using the sequence<T> type. In the current document, the array is documented as T[]. Since Web IDL defines the binding to other languages, in order to make our API successfully be generated to specific language libraries, we'd better follow the exact syntax. 

Here's an example:

typedef sequence<Object> ObjectArray

typedef sequence<DOMString> StringArray

3. About the returnType

* The question is why we inherit each interface to Unstructured interface?

 

If allowed, let's discuss it in today's meeting. 

 

Best Regards, 

 

Hui

 

[1] http://www.w3.org/TR/WebIDL/


[2] http://bondi.omtp.org/default.aspx


[3] http://bondi.omtp.org/1.01/apis/BONDI_Interface_Patterns_v1.0.html#errorhandling