Re: Separate features or not? API for Media Resources 1.0

On 2012-11 -20, at 09:40, Joakim Söderberg wrote:

> Dear Tim, 
> As a preparation for the telephone call coming Monday, the API editors have formulated the following tentative resolution and motivation to your previous concerns:
> 
> In order to clarify the scenarios described in section 3 of the API spec we first try to clarify these scenarios and discuss the reasons that led to specifying both a synchronous and asynchronous mode of the API. 
> 
> Scenario 1 (user agent) considers a client-side only implementation, such as in the user agent or in an extension. "Client-side" only refers to the implementation of the MR API, the media resource and/or the metadata source(s) might still be remote. 

What is important here is the standardization of the interface.
When some code calls some other code, the way it is implemented
should be  irrelevant, if it not irrelevant, then the spec is broken.


> Scenario 2 (web service) considers the client-server case, where the API is provided as a web service, and there is client code accessing the web service. 
> 

Here is is not clear to me where is anywhere the API is called.
On the client side or the server side or bother?

> In both client-only and client-server cases of the implementation, the media resources and/or the metadata sources are in many cases remote, and accessing the metadata sources. The metadata could be embedded into the media resource itself, so reading the metadata might require retrieving and parsing a media file, which may take some time.
> During our work on the specification we have heard from WG members and beyond that an asynchronous mode is thus preferred (also as other specs use this pattern). On the other hand, some people are interested in implementing the API as web service. In that case a synchronous implementation is simpler to achieve, as it avoids the need for two-way communication or polling. This led to the decision of having both modes in the API spec.

If something takes time, then

Mor importantly, if something involves network actions which may
fail, then there must  be a consistent way of getting those errors back to the caller
so that the caller can program for that eventuality.

> 
> We agree to the comment that it is desirable to have full interoperability between both modes. In order to achieve this, we have investigated the option of writing adapter code, which would expose the API of both modes, and emulate one of the modes, in case the actual implementation provides only one of them. 

Certainly, if you have a sync mode you should be able to emulate async.

> 
> The adapter code is an implementation of the MR API as follows:
> - it implements both the synchronous and asynchronous mode of the API
> - it is connected to an implementation X of the MR API
> - it queries the capabilities of implementation X and simply forwards calls for the mode(s) supported by implementation X
> - if implementation X supports only the asynchronous mode, the synchronous implementation in the adapter code calls the asynchronous implementation of X and returns after the callback function is called by X
> - if implementation X supports only the synchronous mode, the asynchronous implementation in the adapter code starts a background thread the calls the synchronous implementation of X and calls the callback function once the call from X returns

Ok, now we have just one API, if that is included in each 


> The adapter code will be implemented in JavaScript and will make use of web workers. It will be provided with the API specification, so that developers can use it in their implementation. We think that this is a viable solution for establishing full interoperability between the two modes of the API. The implementations reported in the implementation report will be updated with this code, thus leading to two implementations covering the all features of the API. 

Tell me about timeouts and network failures.
Does the API define exceptions or error codes for them?

> 
> In order to reflect the proposed changes, Fig. 1 of the API specification has been updated.
> 
> <api_options_v2.pdf>
> 
> 
> 
> Best Regards
> /J Soderberg
>

Received on Monday, 26 November 2012 15:13:20 UTC