Web API Design Cookbook

2.1 Casing

Casing is relatively coherent across the platform, and if you are familiar with JavaScript development it should come to you rather naturally.

Interfaces, dictionaries, exceptions, and callbacks all use “CamelCase”. That is to say no underscores are used and the first letter of every word is in uppercase. The rules when one of those words is an acronym are not necessarily well established — follow your instinct (or try to avoid acronyms).

FascinatingDocument
Node
SomethingBadHappened
XMLHttpRequest

Both attributes and methods use “pascalCase” also known as “interCaps”. Which is to say that the first letter is lowercase, no underscores are used, and all the following logical words in the name start with an uppercase letter.

obj.thisIsAnAttribute
obj.simple
obj.doSomethingNow()
obj.run()

Constants are all uppercase, with logical words separated by underscores. Families of constants tend to have common suffixes. Please note that constants are decreasingly used and that it is likely you will not be having recourse to this construct very much (see Don't Use Numerical Constants).

REALLY_STUPID_ERROR
PASTA_SAUCE_TYPE

Events are a bit special and for historical reasons have somewhat more convoluted rules. The interface that represents a specific event will follow the general rules for interfaces, ending with Event. But the event name will be all lowercase and with no underscores. Likewise, the on* event attribute will be the event name (all lowercase and glued together) simply prefixed with “on”.

SomethingHappenedEvent
obj.addEventListener("somethinghappened", handler, false);
el.onsomethinghappened = handler;

2.2 Using attributes

It is not always obvious when one should use an attribute rather than a method. The basic rule is simple: use attributes as often as possible.

Never use getFoo()/setFoo() accessor pairs unless it is very clear that these are operations that have strong effects beyond just changing the property of the object. If you wish your interface to also be usable in a language other than JavaScript and for which such accessors tend to be needed, the bindings for that language can naturally generate the accessor pair. Don't do this:

var len = obj.getLength();
arr.setLength(num);

But rather:

var len = obj.length;
arr.length = num;

Beyond operations that obviously require a method (that take parameters, return a computed value, carry out an action, etc.) there are specific cases in which what might at first seem like a candidate for being an attribute is best handled as a method:

Modifies the value

In some cases there may be relations between objects such that when one is set as the value of another it needs to be updated to reflect its end of the relationship as well. For instance, when setting objA.child = objB it may be necessary to set objB.parent to objA behind the scenes. Such side effects call for a method: objA.setChild(objB).

Asynchronous access

In some instances, an object may be available but it is best if some of its fields are only loaded lazily because they require time to compute. The canonical example is the size of a file. If processing objects representing files, making the size of each file available immediately will be costly, and acquiring it synchronously upon attribute access would lead to poor performance (those stat calls are not cheap). In such cases it is best to make the accessor an asynchronous method that is passed a callback such as someFile.size(function (bytes) { … }) (or, if there are many such properties on the object, have a single call to load them all, for instance someFile.stat(function (info) { … })).

2.3 When To Be Asynchronous

The Web platform's runtime model is based on a single-threaded event loop. Because of that, any time a method requires even a little bit of time to run, it blocks the thread, and therefore the execution of anything else on the page — leading to bad user experience.

Example of operations that can take a while to complete include reading from the network, accessing the disk, performing a database search, or waking a sensor up.

Another case in which asynchronous operations are required is for all security entry points. Some operations (e.g. obtaining the device's physical location) can require the user agent to obtain the user's permission. If that were to be done synchronously, the entire application would freeze while the user makes her decision. This is undesirable in terms of user experience, but it also a bad security model. The user needs to have all the time she wants in order to make such decisions and should not feel pressured by a frozen application (people make bad security decisions when they want to get something done).

It can seem tempting to make methods either synchronous or asynchronous at the developer's discretion. The simple answer to that is: don't. The result can be catastrophic: for instance, while in development a method that has to interact with a remote resource may return quickly because of light load on the server and proximity between the developer (who is using a powerful device on a fast network) and the server, so that the synchronous call may seem fine. But once deployed, it can cause long, very perceivable freezes for the end-users. The XMLHttpRequest interface does make that option available on its open() method and there is broad consensus that it was a bad decision that should never be emulated.

A context that is not similarly affected by synchronous issues is that of Web Workers (since they run in a separate conceptual thread from the Web application's user interface). In such cases, it can sometimes be useful to provide a synchronous variant of an asynchronous interface that would be available solely in a Worker context. This is primarily done in order to make development simpler in such contexts and should not be considered required.

2.4 Don't Use Numerical Constants

Interfaces regularly require constant identifiers. You have a node and you want to know if it's an element or a comment. You have a message and you want to know if it's email or SMS. That much makes sense. What does not make sense is insisting on naming these things with numbers when we could name them with, you know, names.

There are several variants in this bad practice. First, is the lovingly terse approach:

if (foo.type === 17) doSomething();

Then there is the comment you have to paste every time:

// check if this of the fungible type
if (foo.type === 17) doSomething();

Or we can have the uselessly long variant:

if (foo.type === FooInterface.FUNGIBLE_TYPE) doSomething();

And there's the meh option:

var isFungible = FooInterface.FUNGIBLE_TYPE;
// ...
if (foo.type === isFungible) doSomething();

None of the above is as simple, terse, and self-documenting as:

if (foo.type === "fungible") doSomething();

We're not in the 1970s, standardising UNIX system calls. Strings are lightweight enough, and readable. There is no need to define string constants to support these: just the plain strings, defined as such in specification prose, work. In some languages, this can lose static verification, but in JavaScript it makes no difference: if you misspell the the string you might have equally misspelt the constant, with the same failure.

Additionally, interfaces that don't start out by listing a dozen (useless) constants are more readable. The only downside to doing away with numerical constants is the negative impact it may on occasion have on feature detection. It would however be better to rely on other aspects that enable feature detection, since these constants can easily be added for a half-baked feature (and frequently have been).

2.5 Namespacing and Prefixing

If you are developing functionality for use inside of a Web runtime (but not a browser) that is likely to both share code with existing Web projects (typically, libraries like jQuery) and that also plans to evolve and integrate improvements to the Web platform on a regular basis, then you should make sure that the interfaces and methods you add cannot conflict with ones added to the core platform.

For methods and attributes that extend existing interfaces, you should rely on vendor prefixing, i.e. simply prefixing your additions with a short string that is your company's or project's name.

xhr.acmePassiveFTP();
document.acmeDigitalSignature;

For interfaces that you add, rather than prefixing all of their names which can get tedious, it can be simpler to just make them available under your own namespaced object.

var toaster = new acme.Toaster();

3.1 Using Dictionaries

While designing Web APIs, you might encounter situations where you need to define an interface that has no method. That is, for certain requirements, you need a method to define a property bag object that would be expressed as an Object object or as an object literal in JavaScript implementation. This is where the dictionaries come into play.

This section presents a guideline to use dictionaries at the right place in your specification without any common mistake. First, in the "When to use" section, we show the typical cases you can make use of dictionaries. Second, in the "How to use" section, we provide a list of features that you can check in order not to make a common mistake with dictionary usage.

// WebIDL
partial interface IDBDatabaseSync {
    IDBObjectStoreSync createObjectStore (DOMString name, 
                                          optional IDBObjectStoreParameters optionalParameters);
};

dictionary IDBObjectStoreParameters {
    DOMString? keyPath = null;
    boolean autoIncrement = false;
};

// JavaScript
var parameters = {
    keyPath: "id"
,   autoIncrement: true
};
trans.db.createObjectStore("Contact", parameters);

// WebIDL
[Constructor(IntentParameters params),
 Constructor(DOMString action, DOMString type, optional any data, optional
 sequence<Transferable> transferList)]
interface Intent {
    readonly attribute DOMString     action;
    readonly attribute DOMString     type;
    readonly attribute any           data;
    readonly attribute MessagePort[] ports;
    readonly attribute any           extras;
    void postResult (any data, optional sequence<Transferable> transferable);
    void postFailure (any data);
};

dictionary IntentParameters {
    DOMString              action;
    DOMString              type;
    any                    data;
    sequence<Transferable> transfer;
    Object                 extras;
    URL                    service;
    sequence<URL>          suggestions;
};

// JavaScript
var intent = new Intent({
                          action:    "http://intents.w3.org/pick",
                          type:      "image/png",
                          extras:    { multiple: true, count: 5 },
                          service:   "http://example.com/pick-image"
                      });

// WebIDL
partial dictionary Media {
    MediaContent   content = {};
    DOMString      title;
    DOMString      description;
    DOMString      type = "*.*";
    DOMString     author;
    DOMString     path;
    float         size;
    sequence<DOMString>   tags;
    Date          publishDate;
    Resolution    resolution;
};

// JavaScript
var mediaSequence = [];
var mediaObject = {
    content: { uri: "http://example.com/images/kitten.png" },
    title:        "",
    description:  "",
    type:         "image/png",
    author:       "",
    path:         "/local/path/to/png/kitten.png",
    size:         1000000,
    tags:         ["tom and jerry", "miyau"],
    publishedDate:  "",
    resolution: { width: 1920, height: 1080 }
};
mediaSequence.push(mediaObject);
intent.postResult(mediaSequence);

dictionary IntentParameters {
    DOMString              action;
    DOMString              type;
    any                    data;
    sequence<Transferable> transfer;
    Object                 extras;
    URL                    service;
    sequence<URL>         suggestions;
};

dictionary DoNotUseLikeThis {
    IntentParameters[] params;
};

dictionary UseLikeThis {
    sequence<IntentParameters> params;
};

dictionary Novel : Book {
    // dictionary-members...
};

dictionary Book : Novel {
    // dictionary-members...
};

dictionary PropertyBag {
    DOMString iAmRequired = "default";
    DOMString iAmOptional;
};

interface HasWrongUsage {
    readonly attribute IAmDictionary dict;
};

interface HasRightUsage {
    readonly attribute any dict;
};

dictionary HasWrongUsage {
    IAmDictionary? dict;
};

dictionary HasRightUsage {
    IAmDictionary dict;
};

dictionary SomeDictionary {
    // dictionary-members…
};

partial dictionary SomeDictionary {
    // dictionary-members…
};

3.2 Interfaces

Interfaces are the core work horse of WebIDL as they are the means through which functionality is exposed. They are introduced with the interface keyword, have a name, and a body that contains their definition in terms of constants, attributes, and methods (known as “operations” in WebIDL). A typical interface looks like this:

interface BeerBottle {
    // body goes here
};

Without modifiers, an interface will become available in the global context as an object with the same name.

Interfaces can inherit from other interfaces, in which case they acquire their properties. Inheritance is specified like this:

interface BeerBottle : Bottle {
    // body
};
interface Spork : Spoon, Fork {
    // body
};

As in the last example above, an interface can inherit from any number of other interfaces. This practice however is discouraged if it can be avoided as it entails more complex resolution rules and can be difficult to implement in some contexts. Multiple inheritance is often a sign that the API design should be revisited and can be simplified.

// we wish to add findUnicorns() to Navigator
[NoInterfaceObject]
interface UnicornNavigator {
    Unicorns findUnicorns (DOMString name);
};
Navigator implements UnicornNavigator;
// you can now call navigator.findUnicorns("tab");

partial interface Navigator {
    Unicorns findUnicorns (DOMString name);
};

new Node()
// TypeError: Node is not a constructor

// new Unicorn();
[Constructor]       // the same as [Constructor()]
interface Unicorn {
    // ...
};

// new Unicorn();
// new Unicorn("tab");
// new Unicorn(5, 82);
[Constructor,
 Constructor(DOMString name),
 Constructor(unsigned long wingspan, unsigned long age)]
interface Unicorn {
    // ...
};

// new Rose();
// new Rose("pink");
[NamedConstructor=Rose,
 NamedConstructor=Rose(DOMString colour)]
interface RosoideaeRosa {
    // ...
};

[ArrayClass]
interface ShoppingList {
    attribute unsigned long length;
    getter object getShoppingItem (unsigned long index);
    // note how both creator and setter are used here
    creator setter object setShoppingItem (unsigned long index, object item);
    deleter void removeShoppingItem (unsigned long index);
};

var list = obj.findShoppingListFor("robin");
list = list.concat("beer tea basil ham cat-food".split(" "));
list.forEach(function (item) {
    remindUser("Shop for " + item);
});
list.pop(); // bad cat
console.log("Getting " + list.join("\n"));

3.3 Constants

Constants are a simple construct that does exactly what it say on the tin. It creates a member of a given type on an interface (or an exception) the value of which cannot be changed, introduced with the const keyword.

Constants are limited in the values they can accept. They can take numerical values (including the likes of Infinity and NaN), booleans, or null (for cases in which you might forget what the value of null is). Examples tell you all you need to know about the syntax:

interface Something {
    const short ANSWER = 42;
    const boolean WRONG = false;
    const unsigned long BIG_NUMBER = Infinity;
};

While they were previously used rather commonly, there are decreasing reasons to want to resort to constants on interfaces. Before using them, be sure to be aware of Enums and Don't Use Numerical Constants.

3.4 Enums

An enumeration is used to specify a set of strings that are acceptable, it is typically used to define options that are restricted to a limited vocabulary.

Enumerations are defined with the enum keyword, a type name, and then a list of strings (with no duplicates) inside curly brackets. The name can then be used where type identifiers usually appear.

enum Unit {
    "m",
    "cm",
    "mm"
};
interface Unicorn {
    void setHornSize (unsigned long length, Unit unit);
};
// This works
//    unicorn.setHornSize(42, "cm");
// This blows up as well it should
//    unicorn.setHornSize(7, "in");

When an attribute is defined to be an enumeration type, then assigning a value to it that is not in the enumerated set simply does nothing.

3.5 Attributes

Attributes are a fundamental building block of interfaces. They are used to specify data fields of a given type. An attribute is introduced with the attribute keyword.

They can be read-only in which case they cannot be assigned to, or read-write. It is important to note that if the value of a read-only attribute is not atomic but has attributes of its own, those are not made read-only as well — they keep operating just as specified by that type. An example:

interface Name {
    attribute DOMString givenName;
    attribute DOMString familyName;
};
interface Person {
    readonly attribute Name fullName;
};

In the above definition, it is impossible to assign a new value of the fullName field of Person. So you could not do the following: billie.name = someName;. But the fields of the Name object itself stay just as re-write so that they can still be set, as in billie.name.familyName = "The Cat";.

An attribute can also be said to be static, in which case it is an attribute of the interface rather than being associated with the object. Static attributes are rarely good ideas and can tend to indicate a bad design.

// set the debug flag globally
interface Runtime {
    static attribute boolean debug;
};

A specific behaviour can be added to attributes to define how a given object is turned into a string, using the stringifier modifier. When a object is cast to a string, if a stringifier has been specified (there can be only one) then the string produced will be the value of that attribute. Naturally, that attribute has to be of type DOMString.

// another Person interface
[Constructor(DOMString name, short age)]
interface Unicorn {
    stringifier attribute DOMString fullName;
    attribute short age;
};

This can then be used with the following code:

var uni = new Unicorn("Tab", 42);
document.getElementById("output-unicorn").textContent = uni;
// that element now has content "Tab";

3.6 Methods

Methods are the workhorses of WebIDL. In the specification they are known as “operations”, but since everyone calls them methods we have decided to stick to this term as it will be more readily understood. They are used to define behaviour.

Methods have a return type, and a list of arguments which can be precisely specified. As for attributes, a method can also be said to be static, in which case they become available on the interface object directly.

interface KittenFactory {
    static Kitten makeMeANewKitten (DOMString name);
};
// var billie = KittenFactory.makeMeANewKitten("Billie The Cat");

The return type can be any type or void, which indicates that nothing is returned.

The most complex part of a method's definition is its arguments list. It can contain any number of argument definitions, each of which has a type and a name; all of them separated by commas.

Note that it used to be that arguments were all preceded by the in keyword, which was a leftover from OMG IDL. Since Web specifications make no use of the out and inout argument styles of the aptly named OMG specification, the in keyword has been dropped and must not be used.

A basic method therefore looks like this:

interface Unicorn {
    void gallop (unsigned long speed, Pattern rhythm);
    AudioStream speak ();
};

The arguments can be modified in a number of ways. First, an argument can be marked as optional in which case it can be omitted when the method is invoked. If so, it should be noted that all the arguments that are positioned after it in the list will also be considered optional.

enum Direction { "left", "right" };
interface Dahut {
    void turnAround (optional Direction whichWay, short degrees);
};
// I can call someDahut.turnAround()

Note that in the above it is not indicated that the degrees argument is optional even though it implicitly is. For readability purposes, it is best to always indicate that an argument is optional even when it implicitly is as someone scanning the method definition quickly from the end might not notice it.

A problem with the above method definition is also that while my dahut can only turn left or right, there is no indication of what happens if I omit the argument. Is it right or left? Or random? This can be remedied in specification prose but it is better to specify a default directly in the WebIDL, as follows:

enum Direction { "left", "right" };
interface Dahut {
    void turnAround (optional Direction whichWay = "left", short degrees);
};
// when I call someDahut.turnAround(), it now turns left

An argument can also be variadic. This indicates that that argument can be repeated zero or more times when the method is called. This can only be done if it is the last argument in the arguments list. Variadic arguments are specified by appending "..." to the type.

interface Restaurant {
    DeferredFood orderFood (DOMString... dishName);
};
// I can now call
//  resto.orderFood("spam", "spam", "spam", "spam", "spam", "spam", "spam", "spam", "spam");

3.7 Overloading and Union Types

WebIDL makes it possible to use overloading of methods in interfaces so that there can be more than one method with a given name that takes a different set of arguments. This happens simply by specifying the method more than once.

Note that method overloading is rarely needed and should usually be avoided unless there is no better solution, if only because the restrictions on how it can be used and the resolution rules can be quite complex. A lot of the cases in which one may think that overloading may be required are actually better addressed with optional arguments, variadic arguments, or at times union types.

Union types are used where types can be used, but instead of specifying just one type they indicated that the values can be of several different types. They are specified between parentheses, with each type separated by the or keyword.

interface Party {
    void bookDate ((Date or unsigned long or DOMString) date);
};
// I can now call with...
//  a JS Date object
//    party.bookDate(new Date(…));
//  time since epoch
//    party.bookDate(1337998907987);
//  a magic string
//    party.bookDate("tomorrow");

This can be useful for return values as well:

interface Cryptozoology {
    (Dahut or Unicorn) findAnimal ();
};

3.8 Exceptions

Exceptions are special classes that can be used to be thrown. They are very limited interfaces that can only define constants, and a limited kind of attribute (known as “fields”) that are defined solely by a type and a name.

All exceptions automatically get a message and a name field (for which the specification should provide values), such that those need not be explicitly specified.

It is strongly recommended that new specifications do not define new exceptions, but rather reuse DOMException while providing a specific name for it.

In addition to DOMException, a number of predefined exceptions are also available that can be reused by specifications. This list is: Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError and URIError (these correspond to their JavaScript equivalents as defined in [ECMA-262]).

Due to these constraints on usage, we have decided not to delve deeply into exceptions in this section.

3.9 Callbacks

It is very common for asynchronous methods in Web APIs to accept callbacks, which are functions that can be called with specific arguments when called back. These are specified with the callback keyword, a name, a return type, and an arguments list which is similar to that used for a method.

Specifying callbacks is simple:

// defining callbacks
callback LandingOk = void (unsigned long landingSpeed);
callback LandingFail = void (DOMString gravity, short casualties);

// using callbacks
interface FlyingUnicorn {
    void land (LandingOk, LandingFail);
};

// in code
myFlyingUnicorn.land(
        function (speed) {
            console.log("Successfully landed at " + speed + "kph!");
        }
    ,   function (severity, dead) {
            console.log("Crashed landing. Damage level: " + severity + ". Dead elves: " + dead);
        }
);

3.10 Sequences and Arrays

3.11 WebIDL Legacy Features

The features of WebIDL listed in this section have been specified for the sole purpose of describing legacy APIs such as are found in “DOM 0”. It is particularly important that you do not use them unless you are trying to document one such API — they must not be used for any kind of new work. The list includes:

4.1 Ensuring that Feature Detection is Possible

4.2 Specifying Callbacks

Asynchronous method calls require a point of reentry in the form of a callback. There are multiple ways of specifying these, none of which is consensually consider the one and only approach.

One is success/error callback functions, as used in [GEOLOCATION-API]. It takes the shape of a method call that accepts a callback function for success followed by one for errors. There may be arguments before the success callback, and the error callback is usually optional.

navigator.petKitten(
    function() {
        console.log("kitten is purring");
    },
    function(err) {
        console.log("kitten hates you, because: " + err);
    }
);

Downsides of this approach are that it is a little more verbose and does not encourage error handling. It also lacks in extensibility since adding new arguments to the method will typically require placing them after the optional error handler — making them de facto optional. Likewise, extending it to support not just callbacks for success and error but also for other situations that may warrant reporting information back (e.g. progress being made) is clumsy at best. Since it is only used in [GEOLOCATION-API] it does not appear to be a required pattern for consistency.

Another approach is to define new DOM Events that are called when an underlying system changes.

window.addEventListener("kittenpurr", function() {
    console.log("kitten is purring");
}, false);

On one hand, most developers are quite familiar with DOM Events, and they make it easy to have several handlers for a given event.

On the other hand, using DOM Events for listening to systems that need specific activation (e.g. powering up) are usually not a good idea: addEventListener is supposed to be free from side effects, and associating activation code with it breaks that promise. The [DEVICE-ORIENTATION] specification is as such an anti-pattern that should not be replicated. See some discussions on side effects in addEventListener.

Another is returning an EventTarget object, as pioneered by [XMLHTTPREQUEST]. This consists in opening a request that returns an object on which event handlers can be registered, then starting that request with a specific call.

var kitpet = navigator.openKittenPetting();

kitpet.onpurr = function () {
    console.log("kitten is purring");
};

kitpet.ondrool = function () {
    console.log("kitten is now drooling");
};

kitpet.onviciousbite = function () {
    console.log("kitten bit your hand off");
};

kitpet.start();

The approach is the most verbose and does not encourage error handling, but it does have the advantages of being trivially extended for greater feedback, and of being familiar to users of [XMLHTTPREQUEST] (and now [INDEXEDDB]). It can, however, feel rather overkill if extensions for additional events does not seem likely.

Then there are NodeJS style callbacks. For every asynchronous operation, every callback takes as first parameter an error object which is null when the operation was a success, followed by as many pieces of information as are needed to capture the success.

navigator.petKitten(function (err, state) {
    if (err) console.log("kitten mauled your face with extreme prejudice");
    else console.log("kittem manifest joy by " + state);
});

The primary value in this approach is that it puts errors "right there" where they are likely to be handled. Its consistency is also very helpful in creating chains of callbacks, a feature that proves precious when multiple callbacks can become nested. The major downside of this approach is that it is currently not used in the rest of stack and therefore probably only familiar to NodeJS developers (which granted represent a fast-growing proportion of the general web developer population).

Finally there are promises. These are similar to returning an EventTarget object but more generic and use a slightly different style.

var promise = navigator.petKitten();
promise.then(function () {
    console.log("kitten is purring");
}).fail(function () {
    console.log("kitten bit your hand off");
}).run();

There is elegance and flexibility in promises, but to date they are used in no Web specification.

4.3 Specifying Events