Re: [Fwd: W3C and APIs -- request for agenda item]

>  The attached writeup is from Larry, John and me.

In reading it at the URI it's now at:

  http://lists.w3.org/Archives/Public/www-tag/2009Jun/att-0085/W3C_and_APIs.htm

...I note that there -- where it's now publicly accessible and
standing alone outside the original context of this e-mail
discussion -- there is no way to tell who authored it, because
there's not attribution within the document itself. It might be
helpful to add that and either re-send it to the list so it gets a
different URL, or alternatively just post it at some stable URL.

It would also be helpful if the document had a <title> element.

  --Mike

> W3C and APIs
> 
>    Historically, the W3C has focused primarily on developing clearly
>    declarative languages (such as HTML, and the XML-based languages) and
>    syntactic elements used in protocols. The AWWW [1] says “The Web follows
>    Internet tradition in that its important interfaces are defined in terms
>    of protocols, by specifying the syntax, semantics, and sequencing
>    constraints of the messages interchanged.”
> 
>    But over time, use of scripting languages (and Javascript in particular)
>    and event-based APIs (such as DOM) has increased; today’s HTML
>    specification focuses more on the DOM2 HTML API than it does on the
>    declarative syntax of HTML itself, for example.
> 
>    Recently, the W3C has greatly increased its focus on defining APIs [2,3].
>    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.
> 
>    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.
> 
>    At this point a sceptic might say the W3C offers little guidance to the
>    developers of declarative languages and protocols -- why need we do
>    something different for API developers? But this is not quite true. We do
>    offer some guidance and best practices to developers of declarative
>    languages and protocols: use namespaces for extensibility, use http
>    namespaces, plan for extensibility and versioning, etc. So here are some
>    suggested changes:
> 
>     1. Revise the AWWW [1] to discuss the role of APIs and active content in
>        general.
> 
>     2. 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.
> 
>     3. 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.
> 
>     4. 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.
> 
>     5. 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.
> 
>        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. This seems an
>        important, fundamental area for future work. (One problem with policy
>        is that in a web of autonomous, often anonymous agents, who will
>        enforce policy and where will it be enforced? For example, is it
>        sufficient for GPS devices just have a switch to turn off location
>        broadcasting?)
> 
>     6. 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?
> 
>     7. 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].
> 
>   References
> 
>    [1] [1]http://www.w3.org/TR/webarch/#protocol-interop
> 
>    [2] [2]http://www.w3.org/2009/05/DeviceAPICharter
> 
>    [3] [3]http://www.w3.org/2008/geolocation/drafts/API/
> 
>    [4] [4]http://www.w3.org/2005/10/Process-20051014/tr#rec-advance
> 
>    [5] [5]http://www.w3.org/TR/2009/NOTE-di-testing-20090512/
> 
>    [6] [6]http://dev.w3.org/2006/webapi/WebIDL/
> 
> References
> 
>    Visible links
>    1. http://www.w3.org/TR/webarch/#protocol-interop
>    2. http://www.w3.org/2009/05/DeviceAPICharter
>    3. http://www.w3.org/2008/geolocation/drafts/API/
>    4. http://www.w3.org/2005/10/Process-20051014/tr#rec-advance
>    5. http://www.w3.org/TR/2009/NOTE-di-testing-20090512/
>    6. http://dev.w3.org/2006/webapi/WebIDL/


-- 
Michael(tm) Smith
http://people.w3.org/mike/

Received on Thursday, 18 June 2009 23:40:00 UTC