WebAPI/DesignGuidelines

NOTE

This is a work in progress.

Designing APIs for the web is not an easy task. Here are some suggestions to help.

Considerations

• user privacy and data/hardware security
• fingerprinting
• prompt fatigue (e.g. don't skirt security concerns by prompting to allow the web content to do something as users will have difficulty reading and interpreting the associated risks)
• "web-iness" of what is being exposed to web developers
• work with the strengths of the web and JavaScript (e.g. IndexedDB works directly with JS objects and doesn't require serialization to SQL primitives)
• use new features instead of old ones (e.g. Promises instead of DOMRequests, WebIDL, ...)
• the design of APIs only exposed to privileged or certified apps is less important than those that will be exposed to the web at large
  • standardization is sometimes not necessary for APIs designed for very narrow use cases or those that have no hope of being implemented by other UA vendors
• bringing existing technologies to the web gives a chance to mask details that aren't of interest or important to web developers
• web APIs are "forever" so be very careful with what you expose to the web!

Process

• discuss motivation and design sketches early, often, and widely (e.g. IRC, applicable W3C/WHATWG lists, dev-webapi, dev-platform, dev-gaia, blogs, Twitter, GitHub issues, etc.)
• work with other UA vendors to build consensus
• write a spec and host it somewhere in public
  • easy methods for people to provide feedback and discuss are a bonus (e.g. GitHub issues)
• follow Mozilla's API exposure guidelines (notably sending "Intent to implement" emails)
• in the majority of cases, work through an appropriate W3C or WHATWG group to publish your specification

Resources

• http://wiki.whatwg.org/wiki/FAQ#Is_there_a_process_for_adding_new_features_to_a_specification.3F