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

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. 

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. 

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.

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. 

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

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. 

In order to reflect the proposed changes, Fig. 1 of the API specification has been updated.





Best Regards
/J Soderberg




On 25 Sep 2012, at 16:11, Tim Berners-Lee wrote:

> 
> I'm Ccing www-tag as there is a general question about what
> people mean by features and what we should aim for in terms
> of interop.
> 
> The question in debate is whether Media Resources is ready to 
> come out of CR, without two implementations of each version
> of its API, sync and async.
> 
>> From: Joakim Söderberg <joakim.soderberg@ericsson.com>
>> To: Philippe Le Hegaret <plh@w3.org>
>> Cc: public-media-annotation@w3.org <public-media-annotation@w3.org>
>> Subject: API for Media Resources 1.0
>> Date: Mon, 27 Aug 2012 12:52:32 +0200
>> 
>> Dear Philippe,
>> Here is the WG response to your questions.
>> 
>> a) Availability of the code:
>> All implementations are open source projects. LMF is hosted at Github, the
>> browser extension can be downloaded at the prototype page (the dpi includes
>> the source files and can be extracted similar to a ZIP file). The third
>> implementation (web service) can be downloaded at source forge.
>> 
>> 
>> b) Usage of the API
>> Find included two papers that explain the implementations. They should give
>> the needed details for the browser extension and the server side
>> implementation. The code pieces of the API will soon be available in the LMF
>> branch at Github (maybe with the next major release). Currently it can be
>> found here:
>> 
>> 
>> https://svn.salzburgresearch.at/svn/lmf-media/
>> 
>> 
>> This project needs the complete LMF as dependency. That´s why it seems to be
>> a little bit "tiny".
>> 
>> 
>> c) number of implementations
>> This was discussed, that we do not see the sync and the async mode as
>> separate features.
> 
> Let me understand what your mean by that.
> 
> You can't have your cake and eat it.
> If they are not separate features, then every implementation implements both.
> A client can chose which or a combination of them which it uses, and works
> in either case.
> 
> If servers sometimes implement one without the other, then of course
> interop is much reduced.   (Unless every client is written to work with either).
> You have really two smaller specs which may 
> or may not be each implemented by various servers.
> You have to effectively show that each spec contributes usefully
> to the interop in the world, and the typical way is to show at least two
> interoperable implementations.
> 
> 
> 
>> We have the following paragraph in the status section of
>> the API doc: “The API is designed for both client- and server side
>> implementations.
> 
> Not clear just from that text what it means.  To me, client-side means it
> runs e.g. within the page or an extension, 
> and server side means it runs within a server.
> In either case we are talking about local calls, not remote procedure call.
> 
> Client-server implementations  are a third category, and and as they involve
> network communication, in an event-driven callback environment,
> making them async is important, so that calling code does not hang.
> 
>> Depending on whether the API is implemented in a user agent
>> or plugin, or as a web service, different communication patterns are more
>> appropriate.
> 
> "Communication patterns"?  API design or networ protocol?
> 
>> In the client side case, asynchronous access is typically
>> preferred, while synchronous access is more appropriate for a web service.
> 
> This is the reverse of what I would have thought, assuming client-side
> means local to the client, and 'web service' means a remote call
> over the network. I assume the words are being used differently, 
> "client-side" meaning client-server, and "web service" meaning server-local maybe?
> 
>> Thus the two version of the interface are not considered distinct features
>> but different modes of access for the different use cases.”
> 
> 
> Different modes of access to the same implementation?
> No, I gather not -- these are two quite incompatible APIs.
> Not because they don't look similar in their parameters,
> but because because if you need one and you have the
> other, your code doesn't work.
> 
> Interop means basically that if you have two products, one
> says on its box "Needs x" and the other says on its box
> "Provides x" and you install both, things work.
> 
> Currently, this works with x as MR1.0-async or MR1.0-sync
> but not x as MR1.0.
> 
> In this case, you have to distinguish on the box whether
> it is sync or async. If that is the case, then you have to be 
> up-front about it, the spec defines two APIs. you need to test both,
> and ideally for each show 2 interoperable implementations.
> 
> Tim
> (Not with director decision hat on, just thinkin').
> 
>> 
>> 
>> 
>> 
>>