Some parts of this message have been removed.
Learn more about Nabble's
security policy.
Resending with minor corrections.
--
All the best, Ashok
W3C and APIs
Larry Masinter, John Kemp, Ashok Malhotra
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:
-
Revise the AWWW [1] to discuss the role of APIs and active
content in general.
-
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.
-
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.
-
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.
-
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?)
-
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?
-
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]
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/
