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.

Preparation

• If this is (one of) your first web APIs, keep your scope narrow.
  • With some experience, you'll see fundamental issues with the web platform for which you can propose fixes!
  • If this is your first web API, work with a co-editor that has bandwidth to help you.
• Publicly discuss & document use-cases, motivations, and design sketches early, often, and widely (e.g. IRC, wiki (here on WikiMo or http://wiki.whatwg.org/ ), applicable W3C/WHATWG lists, dev-webapi, dev-platform, dev-gaia, blogs, Twitter, GitHub issues, etc.).
• Avoid scope creep by avoiding trying to fix unrelated problems.
  • For an example of what NOT to do, see Google's "Web Intents", which scope creeped to try to solve all data-to-code-or-service binding/launching problems.
• Iterate and only expand your scope as new features are justified by documented use-cases.
• Start with use cases and requirements.
• Collect currently shipping, available for use examples from other platforms (ex. Android, iOS).
• Determine and document how the existence of these technologies impacts markets (ex. lots of uses in the Google Play store.)
• Find articles, blog post comments, Stack Overflow entries showing that people want this feature on the Web.
• If possible, document how web developers are working around the missing functionality with polyfills and other mechanisms and the drawbacks of this approach (responsive images example of this).
• Use the above to document a need for the API beyond "it would be cool".
• Publish evidence that existing web technologies are not sufficient and that users and developers are being negatively affected by the lack of this feature on the Web.
• Show that there is enough consensus in support of this feature, as further evidence that it would be a good candidate for standardization (the <picture> element did this).
  • Find developers that would make use of this.
  • If you can't find any interested parties then this may not be the right time to standardize your API; keep developing it on an open wiki page incrementally so that others that may be interested might find it in the future.
• Document potential abuse cases and attack vectors.
  • You don't have to know how to address the concerns, just document them.
  • Ask someone to help you find them.
  • Example: http://w3c-webmob.github.io/wake-lock-use-cases/#potential-for-abuse.
• Take these use cases and requirements to a standards body where people can help you format them into a suitable document such as:
  • http://w3c-webmob.github.io/wake-lock-use-cases.
  • http://w3c-webmob.github.io/netinfo-usecases/.
• Expect your uses cases and requirements to evolve as you attempt to standardize.
• Build consensus.
  • Find interested parties who say they'll use this functionality; expressions of interest are critical.
  • Find allies at browser vendors.
  • http://specifiction.org/.
  • https://openwebapps.uservoice.com/.

Standardizing a Feature

• Create a lightweight proposal but be prepared for criticism and expect to make changes:
  • Create a CSS, HTML, and JavaScript version: consider the problem you are trying to solve from multiple angles (even if the CSS or HTML solutions end up being unworkable).
• Keep your proposal short.
• Encourage counter-proposals.
  • Multiple proposals are good so don't be attached to your design in case it doesn't survive.
  • Solving the problem you set out to solve is more important than your proposed API getting standardized.
• In advance, answer questions you anticipate and point people to the answers when they ask related questions.
• If you don't get responses, ask people you know who are more well-known in that community.
• "It takes a village to raise an API".

Specification work

If you get the OK from the standards community, go forth and write a specification.

• Have your work in a public location where people can comment and provide patches.
  • Good choices are Etherpad, Wiki (WikiMo or http://wiki.whatwg.org/ ), GitHub repo, Google Doc, etc. Anything that's collaborative.
• Actual standardization decisions will be made by relevant organization.
  • Ex. a W3C Working Group, a W3C Community Group, the WHATWG, the IETF, etc.
  • See Standards for a list of standards groups and organizations.
• Follow Mozilla's API exposure guidelines (notably sending "Intent to implement" emails).
• Carefully follow the processes of the standards organization within which you are working.
  • There are often legal reasons for these processes.

Design considerations

• Put users first, especially their privacy and the security of their data and hardware.
• Don't fight the Web's security model.
• build on top of existing Web standards.
  • Use common idioms.
  • Don't build on top of features specific to one browser.
• If you are extending the algorithms of another specification, request that the spec you are extending highlights to its readers the points your spec extends/plugs into.
• Document and standardize attack vector mitigations so they're done consistently across implementations.
  • If the attacks can be mitigated either by asking the user or by designing the feature so that there's no need to ask the user, prefer not asking the user.
• Attempt to avoid "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).
• Ensure the API is "webby".
  • If you're coming from a Java, C, or C++ background, you may want to speak with JavaScript people.
• Researching underlying implementations of what you'll be exposing to the Web may help you design something that will ease implementation for the Web.
• 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, ...).
  • But there is nothing wrong with events and such.
  • Don't use new features just for the sake of being cool and hip. Use them when they make sense.
• 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.
• Sometimes it makes sense to limit API exposure to authenticated origins (https) only.
• bringing existing technologies to the Web gives a chance to mask details that aren't of interest or importance to web developers.
• Web APIs are "forever" so be very careful what you expose to the Web! maintain web compatibility!
• Be consistent. No special cases in the APIs.

Tips

• Find someone who has done this before to mentor you on your first attempt.
• Many proposals will fail to get traction, and won't materialize into a standard, but don't be upset: try again in the future.
• Treat people asking questions and those trying to help with respect.
• Collect responses given on mailing lists, via IRC, etc. into your use case documents, FAQs, explainers, etc.; don't rely on people looking through archives.

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
• 10 Practices for Good Open Web Standards Development
• Problems with versioning, part 1: open environments

See Also

• Standards