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.

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

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
>
>
>