canmove, Confirmed users
901
edits
WebAPI/DesignGuidelines: Difference between revisions
Incorporate further input from Marcos, Anne, and Chris Peterson via https://etherpad.mozilla.org/futurestandards
(Incorporate further input from Marcos, Anne, and Chris Peterson via https://etherpad.mozilla.org/futurestandards) |
|||
| Line 4: | Line 4: | ||
Designing APIs for the web is not an easy task. Here are some suggestions to help. | Designing APIs for the web is not an easy task. Here are some suggestions to help. | ||
== | ==Preparation== | ||
* | * keep your scope narrow | ||
* | * discuss motivation and design sketches early, often, and widely (e.g. [[IRC]], applicable W3C/WHATWG lists, [https://lists.mozilla.org/listinfo/dev-webapi dev-webapi], [https://lists.mozilla.org/listinfo/dev-platform dev-platform], [https://lists.mozilla.org/listinfo/dev-gaia dev-gaia], blogs, Twitter, GitHub issues, etc.) | ||
* | * avoid scope creep by avoiding trying to fix unrelated problems | ||
* | * iterate and only expand your scope as new features are needed | ||
* 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) | * 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 impact 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 ([http://usecases.responsiveimages.org/#limitations-of-current-techniques|responsive images example of this]) | |||
* use the above to '''document a need for the API beyond "it would be cool"''' | |||
* document 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 making this 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 | |||
* 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 requirement to a standards body where people can help you format it 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 an API== | |||
* create a lightweight API proposal but be prepared for criticism and expect to make changes | |||
* '''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 | |||
* 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 | |||
** Etherpad, 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. | |||
* follow Mozilla's [[WebAPI/ExposureGuidelines|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 security of their data and hardware | |||
* don't fight the web's security model | |||
* build on top of web standards | |||
** use common idioms | |||
** don't build on top of features specific to one browser | |||
* 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) | * 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, ...) | * use new features instead of old ones (e.g. Promises instead of DOMRequests, WebIDL, ...) | ||
| Line 18: | Line 70: | ||
* web APIs are "forever" so be very careful with what you expose to the web! | * web APIs are "forever" so be very careful with what you expose to the web! | ||
== | ==Tips== | ||
* | * find someone who has done this before to mentor you on your first attempt | ||
* | * many proposals will fail to get traction and materialize into a standard but don't be upset and try again in the future | ||
* treat people asking questions and those trying to help with respect | |||
* | |||
==Resources== | ==Resources== | ||