--- a/api-design/Overview.html Fri Oct 21 11:57:27 2011 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,105 +0,0 @@
-<!DOCTYPE html>
-<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
- <head>
- <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
- <title>API Design Best Practices</title>
- <script class='remove'>
- var respecConfig = {
- specStatus: "ED",
- shortName: "api-design",
- editors: [
- { name: "Robin Berjon",
- url: "http://berjon.com/",
- company: "Robineko",
- companyURL: "http://robineko.com/" }
- ],
- edDraftURI: "http://w3c-test.org/dap/api-design/",
- copyrightStart: 2011,
- noIDLIn: true,
- // wg: "Web Applications (WebApps) Working Group",
- // wgURI: "http://www.w3.org/2008/webapps/",
- // wgPublicList: "public-webapps",
- // wgPatentURI: "http://www.w3.org/2004/01/pp-impl/42538/status",
- wg: "Device APIs Working Group",
- wgURI: "http://www.w3.org/2009/dap/",
- wgPublicList: "public-device-apis",
- wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
- };
- </script>
- <script src='http://respec.specifiction.com/js/profiles/w3c-common.js' class='remove'></script>
- </head>
- <body>
- <section id='abstract'>
- <p>
- This document captures best practices in designing APIs that fit well into the Web platform as
- a whole, using WebIDL [[!WEBIDL]].
- </p>
- </section>
- <section id='sotd'>
- <p>
- As it currently stands, this document is nothing more than a proposal from its editor, with no
- backing implied or otherwise from any other party.
- </p>
- </section>
- <section>
- <h2>Introduction</h2>
- <p>
- Over a relatively short period of time the number of different APIs being created for use on the
- Web has grown at a sustained pace. In working on these interfaces, many in the community discuss
- the benefits of certain approaches over others and reach agreement as to best practices when
- facing a given problem.
- </p>
- <p>
- Keeping track of all these gems is however difficult given the volume of work being carried on
- in parallel and the sometimes disjointed nature of the groups involved. As a result, it can take
- a long while and many arguments repeated almost identically before a discovered best practice
- becomes common.
- </p>
- <p>
- The goal of this document is to capture such ideas as they appear and accrete them over time so as
- to constitute a repository of knowledge on this topic. As a guide it does not however endeavour to
- supplant editors' brains in making decisions as to how to design their APIs, and consequently one
- must keep in mind that the reasoning behind a specific recommendation is often more important than
- its result. Furthermore, in some cases there may not be a single consensual best approach, and
- editors will need to understand the tradeoffs involved in order to pick what works for them amongst
- a set of options.
- </p>
- </section>
- <section>
- <h2>WebIDL Legacy Features</h2>
- <p>
- ...
- </p>
- </section>
- <section>
- <h2>Exceptions</h2>
- <p>
- ...
- </p>
- </section>
- <section>
- <h2>When to use NoInterfaceObject</h2>
- <p>
- ...
- </p>
- </section>
- <section>
- <h2>Using Dictionaries</h2>
- <p>
- ...
- </p>
- </section>
- <section>
- <h2>Specifying Callbacks</h2>
- <p>
- ...
- </p>
- </section>
- <section class='appendix'>
- <h2>Acknowledgements</h2>
- <p>
- Many thanks to Cameron McCormack, Marcos Càceres, and Andreas Gal for their input.
- </p>
- </section>
- </body>
-</html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/api-design/index.html Thu Nov 10 12:32:23 2011 +0100
@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
+ <head>
+ <meta http-equiv='Content-Type' content='text/html; charset=utf-8'/>
+ <title>API Design Best Practices</title>
+ <script class='remove'>
+ var respecConfig = {
+ specStatus: "ED",
+ shortName: "api-design",
+ editors: [
+ { name: "Robin Berjon",
+ url: "http://berjon.com/",
+ company: "Robineko",
+ companyURL: "http://robineko.com/" }
+ ],
+ edDraftURI: "http://w3c-test.org/dap/api-design/",
+ copyrightStart: 2011,
+ noIDLIn: true,
+ // wg: "Web Applications (WebApps) Working Group",
+ // wgURI: "http://www.w3.org/2008/webapps/",
+ // wgPublicList: "public-webapps",
+ // wgPatentURI: "http://www.w3.org/2004/01/pp-impl/42538/status",
+ wg: "Device APIs Working Group",
+ wgURI: "http://www.w3.org/2009/dap/",
+ wgPublicList: "public-device-apis",
+ wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
+ };
+ </script>
+ <script src='http://respec.specifiction.com/js/profiles/w3c-common.js' class='remove'></script>
+ </head>
+ <body>
+ <section id='abstract'>
+ <p>
+ This document captures best practices in designing APIs that fit well into the Web platform as
+ a whole, using WebIDL [[!WEBIDL]].
+ </p>
+ </section>
+ <section id='sotd'>
+ <p>
+ As it currently stands, this document is nothing more than a proposal from its editor, with no
+ backing implied or otherwise from any other party.
+ </p>
+ </section>
+ <section>
+ <h2>Introduction</h2>
+ <p>
+ Over a relatively short period of time the number of different APIs being created for use on the
+ Web has grown at a sustained pace. In working on these interfaces, many in the community discuss
+ the benefits of certain approaches over others and reach agreement as to best practices when
+ facing a given problem.
+ </p>
+ <p>
+ Keeping track of all these gems is however difficult given the volume of work being carried on
+ in parallel and the sometimes disjointed nature of the groups involved. As a result, it can take
+ a long while and many arguments repeated almost identically before a discovered best practice
+ becomes common.
+ </p>
+ <p>
+ The goal of this document is to capture such ideas as they appear and accrete them over time so as
+ to constitute a repository of knowledge on this topic. As a guide it does not however endeavour to
+ supplant editors' brains in making decisions as to how to design their APIs, and consequently one
+ must keep in mind that the reasoning behind a specific recommendation is often more important than
+ its result. Furthermore, in some cases there may not be a single consensual best approach, and
+ editors will need to understand the tradeoffs involved in order to pick what works for them amongst
+ a set of options.
+ </p>
+ </section>
+ <section>
+ <h2>WebIDL Legacy Features</h2>
+ <p>
+ ...
+ </p>
+ </section>
+ <section>
+ <h2>Exceptions</h2>
+ <p>
+ ...
+ </p>
+ </section>
+ <section>
+ <h2>When to use NoInterfaceObject</h2>
+ <p>
+ ...
+ </p>
+ </section>
+ <section>
+ <h2>Using Dictionaries</h2>
+ <p>
+ ...
+ </p>
+ </section>
+ <section>
+ <h2>Specifying Callbacks</h2>
+ <p>
+ ...
+ </p>
+ </section>
+ <section class='appendix'>
+ <h2>Acknowledgements</h2>
+ <p>
+ Many thanks to Cameron McCormack, Marcos Càceres, and Andreas Gal for their input.
+ </p>
+ </section>
+ </body>
+</html>