WebAPI/DesignGuidelines: Difference between revisions

Point people elsewhere as this is not maintained
(Point people elsewhere as this is not maintained)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div style="margin: 1em 0px; border: 2px solid orange; padding: 1em; background-color: orange; text-align: center;">'''NOTE'''
<div style="margin: 1em 0px; border: 2px solid orange; padding: 1em; background-color: orange; text-align: center;">'''NOTE'''
<div style="font-size:x-small">This is a work in progress.</div></div>
<div>This is not actively maintained. [https://w3ctag.github.io/design-principles/ Web Platform Design Principles] is probably a better starting point.</div></div>


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.
Line 7: Line 7:
* If this is (one of) your first web APIs, keep your scope narrow.
* 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!
** 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.
** If this is your first web API, work with a co-editor who 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, [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.).
* 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, [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.
* Avoid scope creep by avoiding trying to fix unrelated problems.
Line 54: Line 54:
** Ex. a W3C Working Group, a W3C Community Group, the WHATWG, the IETF, etc.
** Ex. a W3C Working Group, a W3C Community Group, the WHATWG, the IETF, etc.
** See [[Standards]] for a list of standards groups and organizations.
** See [[Standards]] for a list of standards groups and organizations.
* Follow Mozilla's [[WebAPI/ExposureGuidelines|API exposure guidelines]] (notably sending "Intent to implement" emails).
* 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.
* Carefully follow the processes of the standards organization within which you are working.
** There are often legal reasons for these processes.
** There are often legal reasons for these processes.
Line 99: Line 99:
== See Also ==
== See Also ==
* [[Standards]]
* [[Standards]]
[[Category:Web APIs]]
Confirmed users
112

edits