This document captures best practices in designing APIs that fit well into the Web platform as a whole, using WebIDL [[!WEBIDL]].

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.


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.

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.

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.

WebIDL Legacy Features



Web IDL forbids exception fields named "message" (and "name"). This property will exist automatically as an own property on the exception object if a message is specified when throwing the exception. So you just need to say, for example.

How to write:

Throw an FooException of type "SomeError" with message "Something went wrong!".

When to use NoInterfaceObject


Using Dictionaries


Specifying Callbacks



Many thanks to Cameron McCormack, Marcos Càceres, and Andreas Gal for their input.