API Design Cookbook by Robin Berjon


From the readme:

This is a cookbook produced jointly at W3C by:

* The Script Library Community Group (http://www.w3.org/community/scriptlib/)
* The Device APIs Working Group (http://www.w3.org/2009/dap/)
* The WebApps Working Group (http://www.w3.org/2008/webapps/)

Its goal is to document common practices in the production of Web APIs for usage in JavaScript.
We are shying away from calling these “Best Practices” for two reasons:

* Sometimes there are several options and picking one is a matter of tradeoffs rather than
obvious superiority.
* It is possible that some options may not be the best in an ideal “start from scratch” world,
but are nevertheless the ones recommended here for consistency with the rest of the platform.

We are also refraining from calling these “patterns”. Our goals are more concrete than that.

Broad feedback from everyone is very much desired. If you are interested, please join the
Script Library Group (it is not just open but also friendly to all). Details can be found at

2 Responses to API Design Cookbook by Robin Berjon

  1. Stefan Haustein says:

    The HTML 5 Canvas spec (1) provides link targets of the form

    CONSTANT_PREFIX + interfaceName.toLowerCase() + “-” + operationName.toLowercase();

    This makes it quite easy to link to the relevant parts of the specification, for instance in IDEs and / or generated JavaDoc comments. Unfortunately, other specifications such as WebGL or TypedArrays do not follow this schema.

    Do you think it would make sense to support this link schema as a general recommendation in the API design cookbook?


    1) http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html

    Discussion on WebIDL: http://lists.w3.org/Archives/Public/public-script-coord/2012JanMar/0290.html

  2. Marcos Caceres says:

    Hi Stefan, although I like the consistency, I don’t think we should recommend such things. Spec generation tools often use their own schemes for generating section and definition ids.

Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Before you comment here, note that this forum is moderated and your IP address is sent to Akismet, the plugin we use to mitigate spam comments.