API Design Cookbook by Robin Berjon
Posted on:https://github.com/scriptlib-cg/api-design-cookbook
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
http://www.w3.org/community/scriptlib/.
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?
Stefan
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
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.