- From: Robin Berjon <robin@berjon.com>
- Date: Fri, 19 Jun 2009 12:51:48 +0200
- To: www-tag@w3.org
Hi,
a few notes on the topic of APIs.
On Jun 18, 2009, at 21:12 , ashok malhotra wrote:
> Recently, the W3C has greatly increased its focus on defining APIs
> [2,3].
>
I am unconvinced that the increase is as strong as it is made out to
be. W3C has produced a fair number of APIs over the years: just the
sum total of all the DOM specifications, plus the HTML DOM, SVG DOM,
and CSS OM already add up to a lot of interfaces. The initial WebAPI
WG (now WebApps) was chartered a few years back with already a large
set of APIs in its remit. Before that, the SVG WG had been working on
a number of non-DOM APIs as well. And then there's Geolocation, DCI
(fka DPF) and a few others I'm probably forgetting about.
I think that the shift, if shift there is, has more to do with what we
are defining APIs to. The early ones were more internally oriented,
whereas the upcoming ones are turned more towards the outside world.
I'm unsure that this is an issue though, rather than simply a
manifestation of the fact that the web is extending its rosy fingers
well outside of the browser.
> This raises the question of whether the W3C TAG should offer further
> guidance to the developers of APIs, and whether (or how) that
> guidance should differ from that offered to the developer of a
> declarative language or protocol.
>
I would add: and whether it should differ from guidance offered to
APIs previously defined within W3C.
> APIs are often described by means of an interface definition
> language (such as WebIDL[6]) adding yet another language to the
> heady mix available on the Web today.
>
I am unsure what to make of this comment. WebIDL fills a very useful
gap: it provides formalism and an interoperable translation to
Javascript interfaces for the APIs that we can define. Early W3C APIs
were defined using OMG IDL, but it eventually turned out to be a poor
match for the type of interfaces often desired. This lead to a number
of W3C specifications being released that used something that looked
like IDL, but wasn't valid according to any definition, and did not
have binding translations to Javascript.
The OMTP BONDI Interfaces group also experimented with using Java
interfaces for this purpose, but they too were found lacking in
several respects which together with Java's quasi-irrelevance in a web
content context caused that approach to be abandoned in favour of
WebIDL.
Work on WebIDL is painstaking and understaffed if we had had a
better option available I'm pretty sure that everyone would have been
happy to reuse it. I'm sure the WebApps WG would therefore welcome
pointers to viable alternatives within that "heady mix available on
the Web today" of which you speak.
> Revise the AWWW [1] to discuss the role of APIs and active content
> in general.
That would certainly be worthwhile. OMTP BONDI and WebApps have both
had heated arguments about versioning, to the point where asking which
version of the versioning argument we're on now has become a trite
joke. And I expect that ugly baby to come back in DAP.
A balanced take on how APIs and markup complement one another could
also prove helpful that debate has been making rounds for too long
and should be put to sleep.
> The process document [4] says
, the Working Group SHOULD be
> able to demonstrate two interoperable implementations of each
> feature. Clarify what this means for APIs insofar as APIs are often
> embedded in, or used in context with, other languages.
I am not convinced that this is a useful topic to clarify. A WG
typically has a fairly good idea of its community and industry
(otherwise, it has issues more serious than its CR exit criteria). If
it finds that it needs its test suite to operate in a single language
or in twenty, it's probably right (and probably won't listen to the
TAG telling it otherwise).
> Think through what we want to say about versioning and
> extensibility. It may be even more important for extended versions
> of APIs to work with old devices than for HTML to work with old
> browsers.
It's just as important, and the same fundamental rules apply.
> The failure model may be different. If the implementation does not
> understand a statement, what does it do: error, crash and burn,
> ignore? In typical interface definition languages, this is handled
> by describing exception cases which are documented for a particular
> interface.
This should be up to the concrete implementation language, not the
IDL. At some point the extensibility model has to hit the road, and
you can't usefully enforce support for a feature across languages. It
was tried with DOM's hasFeature(), which in practice produces
completely untrustable results.
> Subverting the traditional client-server model of the Web (by
> allowing a client to effectively serve Web content via an API call)
> has implications (particularly in the areas of security and privacy)
> for the relationship between a client and a server.
I'm not sure that this is ever really happening. The client can write
to services but that's always been part of the web (even if often
insufficiently so). If you're thinking about things like Opera Unite I
don't believe it changes anything: it's a client and it's a server,
and there's a nice UI to the latter in the former, but that's about
it. No architectural change.
> The Geolocation API [3] and the Device APIs Charter [2] both mention
> security and privacy policies but, as yet there are large
> disagreements on what shape such policies should take.
>
That's precisely the "Policy" part of DAP.
> There may be a need for guidance on how an API should be embedded
> in other Web content. For example, in Geolocation the host language
> identifies the device while the API specifies operations on the
> device. Similarly, if there is an error during the processing of an
> API request, how is that reported to the host content?
>
Could you please clarify what you meant here? I'm not sure how we need
to change existing models here.
> Testing APIs is different from testing protocols at least, in part
> due to wide variability in features between implementations of the
> API. For example, the Mobile Test Initiative has made a good start
> by publishing a note on how to write device-independent tests for
> mobile devices [5].
I think the largest chunk that needs to be clear here is capability-
based testing, i.e. how can I conform to the Camera API if I'm a user-
agent running on a device that doesn't have a camera?
--
Robin Berjon - http://berjon.com/
Feel like hiring me? Go to http://robineko.com/
Received on Friday, 19 June 2009 10:52:27 UTC