View source for TPAC/2011/API Design Approaches and the Rationales for Them

===API Design Approaches and the Rationales for Them===

* Led by: Bryan Sullivan/proposed by Ileana Leuca

What API design approaches are browser vendors seeking to promote, and what are the rationales for the choices? How can W3C help the wider Web community (including SDOs that want to Web-enable their standards-based service enablers, or extend the Web platform with new capabilities) follow a successful path to convergence with W3C? For example what are the rationales behind the following API design approaches?

* declarative (via markup language features, e.g. HTML5's <video> tag)
* Javascript (object/procedural interfaces ala window.open())
* XHR/REST (using HTTP scheme URLs such as in conventional RESTful Web APIs, and non-HTTP scheme URLs handled by the browser or some local system-registered URL handler)

===Results from the Session===

Session discussion outline: http://www.w3.org/2011/Talks/1102-api-bryan/
See also [http://www.w3.org/2011/11/02-apidesign-irc.html raw minutes]
 
The key points captured from the session:
* Data Minimization (draft: http://www.w3.org/2001/tag/doc/APIMinimization.html) for privacy protection is one of the key considerations in API design.
* The audience for the API should be considered. Different audiences will have interest in different API approaches (e.g. declarative vs JavaScript). To help ensure an effective API is developed, API design should follow a progressive path by identifying customers, their use cases, prototyping designs, and settling on specs and syntax. The hands-on experience with early prototypes will help ensure that the API design is effective. The audience from which input on APIs should be sought should expand progressively as the API is developed, and the feedback should help refine the API.
* Design guidelines are valuable parts of the process. They should be living, but mostly non-normative. We need to be able to evolve design approaches and practices.
* API design extensibility is a key consideration.
* APIs should be usable. We need to learn from why developers need libraries, e.g. by reaching out to the library developers for their input. 
* If we don't standardize higher level APIs someone will often later come along with a library that sets a de facto standard (as in JQuery). An objective is to target APIs for no JavaScript library dependency. Requiring a library from the start is a indicator that possibly something is wrong. BUT: APIs need to be targeted for use cases, in the range from low level to high level. It is reasonable for a low-level API which needs a high-level JavaScript abstraction to give the group time to figure out what the high-level API needs to be. 
* APIs that deal with I/O or user input should be async, and result in non-blocking user experience. But sync APIs may be acceptable where the performance impact of the API is minimal.