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?
[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