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

• start with a use case which you're trying to solve, and try to avoid scope creep to fix unrelated problems
• design the solution at the right level, for example if the use case is to address a specific UX requirement, think of how you can design the API to keep it intact in the face of future changes to the UX requirements. Sometimes this means designing a lower level API with the expectation of some client code being written on top of it to satisfy the existing UX requirements.
• 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 to get right the first time than those that will be exposed to the web at large but if this route is chosen, future standardization efforts will be hampered
• 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
• https://github.com/w3ctag/promises-guide
• http://annevankesteren.nl/2014/08/asynchronicity
• http://annevankesteren.nl/2014/03/contributing-to-standards
• http://annevankesteren.nl/2014/02/monkey-patch