Client-side API Design Principles

A Collection of Interesting Ideas,

Sangwhan Moon (Invited Expert)
Former Editor:
Domenic Denicola (Google)
Members of the TAG, past and present
GitHub w3ctag/design-principles (file an issue; open issues)


This document contains a small-but-growing set of design principles collected by the W3C TAG while reviewing specifications.

1. JavaScript Language

1.1. Web APIs are for JavaScript

The language that web APIs are meant to be used in, and specified for, is JavaScript (also known as [ECMASCRIPT]). They are not language-agnostic, and are not meant to be.

This is sometimes a confusing point because [WEBIDL] descended from the language-agnostic OMG IDL (and at one point, included "Java Bindings"). Even today, the structure of the document contains a confusing and redundant division between the "Interface definition language" and the "ECMAScript binding". Rest assured that this division is simply a historical artifact of document structure, and does not imply anything about the intent of Web IDL in general. The only reason it remains is that nobody has taken the time to eradicate it.

As such, when designing your APIs, your primary concern should be with the interface you present to JavaScript developers. You can freely rely upon language-specific semantics and conventions, with no need to keep things generalized.

1.2. Preserve run-to-completion semantics

Web APIs are essentially vehicles for extruding C++- (or Rust-) authored capabilities into the JavaScript code that developers write. As such, it’s important to respect the invariants that are in play in normal JavaScript code. One of the most important of these is run-to-completion semantics: wherein each turn of the JavaScript event loop is processed completely before returning control to the user agent.

In particular, this means that JavaScript functions cannot be preempted mid-execution, and thus that any data observed within the function will stay constant as long as that function is active. This is not the case in other languages, which allow data races via multithreading or other techniques—a C function can be preempted at any time, with the bindings it has access to changing values from one line to the next.

This no-data-races invariant is extensively relied upon in JavaScript programs. As such, the invariant must never be violated—even by web APIs, which are often implemented in languages that do allow data races. Although the user agent may be using threads or other techniques to modify state in parallel, web APIs must never expose such changing state directly to developers. Instead, they should queue a task to modify author-observable state (such as an object property).

1.3. Do not expose garbage collection

There must not be a way for author code to deduce when/if garbage collection of JavaScript objects has run.

The reason for this is somewhat subtle. If garbage collection timing were observable, then authors could easily write code relying on specific garbage collection timing. But this timing is almost certainly not the same across user agents, which means the resulting code will be non-interoperable. Worse, according to the usual rules of game theory as applied to browsers, this kind of scenario could force other user agents to copy the garbage collection timing of the original in order to create interoperability. This would cause current garbage collection strategies to ossify, preventing improvement in one of the most dynamic areas of JavaScript virtual machine technology.

In particular, this means that you can’t expose any API that acts as a weak reference, e.g. with a property that becomes null once garbage collection runs. Such freeing of memory must be entirely deterministic.

There is some speculative discussion of exposing weak references such that their finalization is only observable between event loop turns in this stage 1 proposal under discussion at TC39. However, this remains contentious and does not yet have consensus in TC39 or among implementers.

2. API Surface Concerns

2.1. Naming things

Naming is hard! We would all like a silver-bullet for naming APIs...

Names take meaning from:

Consistency is a good principle that helps to create a platform that users can navigate intuitively and by name association.

Please consult widely on names in your APIs.

2.2. New features should be detectable

The existence of new features should generally be detectable, so that web content can act appropriately whether the feature is present or not. This applies both to features that are not present because they are not implemented, and to features that may not be present in a particular configuration (ranging from features that are present only on particular platforms to features that are only available in secure contexts).

It should generally be indistinguishable why a feature is unavailable, so that feature detection code written for one case of unavailability (e.g., the feature not being implemented yet in some browsers) also works in other cases (e.g., a library being used in a non-secure context when the feature is limited to secure contexts).

Detection should always be possible from script, but in some cases the feature should also be detectable in the language where it is used (such as @supports in CSS).

2.3. Attributes should behave like data properties

[WEBIDL] attributes are reified in JavaScript as accessor properties, i.e. properties with separate getter and setter functions which can react independently. This is in contrast to the "default" style of JavaScript properties, data properties, which do not have configurable behavior but instead can simply be set and retrieved, or optionally marked read-only so that they cannot be set.

Data property semantics are what are generally expected by JavaScript developers when interfacing with objects. As such, although getters and setters allow infinite customizability when defining your Web IDL attributes, you should endeavor to make the resulting accessor properties behave as much like a data property as possible. Specific guidance in this regard includes:

2.4. Consider whether objects should be live or static

Objects returned from functions, attribute getters, etc., can either be live or static. A live object is one that continues to reflect changes made after it was returned to the caller. A static object is one that reflects the state at the time it was returned.

Objects that are the way state is mutated are generally live. For example, DOM nodes are returned as live objects, since they are the API through which attributes are set and other changes to the DOM are made. They also reflect changes to the DOM made in other ways (such as through user interaction with forms).

Objects that represent a collection that might change over time (and that are not the way state is mutated) should generally be returned as static objects. This is because it is confusing to users of the API when a collection changes while being iterated. Because of this, it is generally considered a mistake that methods like getElementsByTagName() return live objects; querySelectorAll() was made to return static objects as a result of this experience. On the other hand, even though URLSearchParams represents a collection, it should be live because the collection is mutated through that object.

Note: It’s possible that some of this advice should be reconsidered for maplike and setlike types, where iterators have reasonable behavior for mutation that happens during iteration. This point likely needs further discussion, and perhaps further experience of use of these types.

It’s also worth considering the implications of having live versus static objects for the speed of implementations of the API. When the data needed by an object are expensive to compute up-front, there is an advantage for that object to be live so that the results can be computed lazily, such as for getComputedStyle(). On the other hand, if the data needed by an object are expensive to keep up-to-date, such as for the NodeList returned from querySelectorAll(), then providing a static object avoids having to keep the object updated until it is garbage collected (which may be substantially after its last use).

Likewise, the choice of live versus static objects can influence the memory use of an API. If each call of a method returns a new static object, and the objects are large, then substantial amounts of memory can be wasted until the next garbage collection.

The choice of whether an object is live or static may also influence whether it should be returned from an attribute getter or from a method. See §2.3 Attributes should behave like data properties. In particular, if a result that changes frequently is returned as a static object, it should probably be returned from a method rather than an attribute getter.

2.5. Use casing rules consistent with existing APIs

Although they haven’t always been uniformly followed, through the history of web platform API design, the following rules have emerged:

Casing rule Examples
Methods and properties
(Web IDL attributes, operations, and dictionary keys)
Camel case document.createAttribute()
Classes and mixins
(Web IDL interfaces)
Pascal case NamedNodeMap
Initialisms in APIs All caps, except when the first word in a method or property HTMLCollection
Repeated initialisms in APIs Follow the same rule HTMLHRElement
The abbreviation of "identity" Id, except when the first word in a method or property node.getElementById()
Enumeration values Lowercase, dash-delimited "no-referrer-when-downgrade"
Events Lowercase, concatenated autocompleteerror
HTML elements and attributes Lowercase, concatenated <figcaption>
<textarea maxlength>
JSON keys Lowercase, underscore-delimited manifest.short_name
Note that in particular, when a HTML attribute is reflected as a property, the attribute and property’s casings will not necessarily match. For example, the HTML attribute ismap on img elements is reflected as the isMap property on HTMLImageElement.

The rules for JSON keys are meant to apply to specific JSON file formats sent over HTTP or stored on disk, and don’t apply to the general notion of JavaScript object keys.

Repeated initialisms are particularly non-uniform throughout the platform. Infamous historical examples that violate the above rules are XMLHttpRequest and HTMLHtmlElement. Do not follow their example; instead always capitalize your initialisms, even if they are repeated.

2.6. Prefer dictionary parameters over boolean parameters or other unreadable parameters

APIs should generally prefer dictionary parameters (with named booleans in the dictionary) over boolean parameters. This makes the code that calls the API much more readable. It also makes the API more extensible in the future, particularly if multiple booleans are needed.

For example, new Event("exampleevent", { bubbles: true, cancelable: false}) is much more readable than new Event("exampleevent", true, false).

Furthermore, the booleans in dictionaries need to be designed so that they all default to false. If booleans default to true, then users of the API will find unexpected JavaScript behavior since { passive: false } and { passive: undefined } will produce different results. But at the same time, it’s important to avoid naming booleans in negative ways, because then code will have confusing double-negatives. These pieces of advice may sometimes conflict, but the conflict can be avoided by using opposite words without negatives, such as “repeat” versus “once”, “isolate” versus “connect”, or “private” versus “public”.

Likewise, APIs should use dictionary parameters to avoid other cases of difficult to understand sequences of parameters. For example, window.scrollBy({ left: 50, top: 0 }) is more readable than window.scrollBy(50, 0).

2.7. Design asynchronous APIs using Promises

Asynchronous APIs should generally be designed using promises rather than callback functions. This is the pattern that we’ve settled on for the Web platform, and having APIs consistently use promises means that the APIs are easier to use together (such as by chaining promises). This pattern also tends to produce cleaner code than the use of APIs with callback functions.

Furthermore, you should carefully consider whether an API might need to be asynchronous before making it a synchronous API. An API might need to be asynchronous if:

For more information on how to design APIs using promises, and on when to use promises and when not to use promises, see Writing Promise-Using Specifications.

3. Event Design

3.1. Always add event handler attributes

For an object that inherits from EventTarget, there are two techniques available for registering an event handler (e.g., an event named "somethingchanged"):

  1. addEventListener() which allows authors to register for the event using the event’s name (i.e., someobject.addEventListener("somethingchanged", myhandler)) and

  2. onsomethingchanged IDL attributes which allow one event handler to be directly assigned to the object (i.e., someobject.onsomethingchanged).

Because there are two techniques for registering events on objects inheriting from EventTarget, authors may be tempted to omit the corresponding event handler IDL attributes. They may assume that event handler IDL attributes are a legacy registration technique or are simply not needed given that addEventListener() is available as an alternative. However, it is important to continue to define event handler IDL attributes because:

So, if the object inherits from EventTarget, add a corresponding onyourevent event handler IDL attribute to the interface.

Note that for HTML and SVG elements, it is traditional to add the event handler IDL attributes on the GlobalEventHandlers interface, instead of directly on the relevant element interface(s).

3.2. Events are for notification

Try to design DOM events to deliver after-the-fact notifications of changes. It may be tempting to try to trigger side-effects from the action of dispatchEvent, but in general this is strongly discouraged as it requires changes to the DOM specification when added. Your design will proceed more quickly if you avoid this pattern.

3.3. Favor asynchronous events

A few events in the platform are specified to dispatch synchronously. These events cause problems for engines and performance issues in applications due to the possibility for re-entrant behavior they open up. The deprecated Mutation Events, for instance, has caused many years of security issues. A more modern approach embodied in Mutation Observers addresses most of the same use-cases in a higher-performance way which is easier to develop with and implement. If you feel you need a synchronous event in your design, please reconsider and ask the TAG for help in redesigning the API.

3.4. State and Event subclasses

It’s tempting to create subclasses of Event for all event types. This is frequently unnecessary. Consider subclassing Event when adding unique methods and large amounts of state. In all other cases, using a "vanilla" event with state captured in the .target object.

4. Types and Units

4.1. Use numeric types appropriately

[WEBIDL] contains many numeric types. However, it is very rare that its more specific ones are actually appropriate.

JavaScript has only one numeric type, Number: IEEE 754 double-precision floating point, including ±0, ±Infinity, and NaN (although thankfully only one). The Web IDL "types" are coercion rules that apply when accepting an argument or triggering a setter. For example, a Web IDL unsigned short roughly says: "when someone passes this as an argument, take it modulo 65535 before doing any further processing". That is very rarely a useful thing to do.

Instead, you will want to stick with one of:

unrestricted double

When truly any JavaScript number will do, including infinities and NaN


Any JavaScript number excluding infinities and NaN

[EnforceRange] long long

Any JavaScript number in the integer-representable range, throwing a TypeError outside the range and rounding inside of it

[EnforceRange] unsigned long long

Any nonnegative JavaScript number in the integer-representable range, throwing a TypeError outside the range and rounding inside of it

Additionally, you can combine any of the above with an extra line in your algorithm to validate that the number is within the expected domain-specific range, and throwing or performing other actions in response. (While it is very rarely appropriate to modify author input by taking it modulo 65535, it might be appropriate to take it modulo 360, for example.)

A special case of domain-specific validation, which Web IDL already has you covered for, is the 0–255 range. This can be written as [EnforcedRange] octet: any JavaScript number in the range 0–255, throwing a TypeError outside the range and rounding inside of it. (And indeed, if it turns out that the other power-of-two ranges are semantically meaningful for your domain, such that you want the modulo or range-checking behavior, feel free to use them.)

Those coming from other languages should carefully note that despite their names, long long and unsigned long long only have 53 bits of precision, and not 64.

4.2. Use milliseconds for time measurement

Any web API that accepts a time measurement should do so in milliseconds. This is a tradition stemming from setTimeout and the Date API, and carried through since then.

Even if seconds (or some other unit) are more natural in the domain of an API, sticking with milliseconds ensures interoperability with the rest of the platform, allowing easy arithmetic with other time quantities.

Note that high-resolution time is usually represented as fractional milliseconds, not e.g. as nanoseconds.

4.3. Use the appropriate type to represent times and dates

When representing date-times on the platform, use the DOMTimeStamp type, with values being the number of milliseconds relative to 1970-01-01T00:00:00Z.

The JavaScript Date class must not be used for this purpose. Date objects are mutable (and there is no way to make them immutable), which comes with a host of attendant problems.

For more background on why Date must not be used, see the following:

While in theory time is monotonically increasing, values like DOMTimeStamp that represent time since 1970 are derived from the system’s clock, which may sometimes move backwards (for example, from NTP or manual adjustment), causing the timestamp values to decrease over time. They may also remain the same due to the limitation of millisecond resolution. Thus, for time stamps that do not need to correspond to an absolute time, consider using DOMHighResTimeStamp, which provides monotonically non-decreasing sub-millisecond timestamps that are comparable within a single browsing context or web worker. See [HIGHRES-TIME] for more details.

4.4. Use Error or DOMException for errors

Errors in web APIs should be represented as ECMAScript error objects (perhaps via the WebIDL Error type) or as DOMException. There was at one point a trend to use DOMError when objects had a property representing an error. However, we no longer believe there was value in this split, and therefore suggest that ECMAScript error objects (e.g., TypeError) or DOMException should be used for errors, whether they are exceptions, promise rejection values, or properties.

5. Device APIs

It is increasingly common to see new APIs developed in the web platform for interacting with devices. For example, authors wish to be able to use the web to connect with their microphones and cameras, generic sensors (such as gyroscope and accelerometer), Bluetooth and USB-connected peripherals, automobiles, toothbrush, etc. This section contains principles for consideration when designing APIs for devices.

5.1. Use care when exposing device identifiers

Exposing device identifiers increases the fingerprinting surface of a user agent conversely reducing the user’s privacy. Think carefully about whether it is really necessary to expose the unique identifier at all. Please read the TAG’s finding on unsanctioned tracking for additional details. Despite this general concern, it may be very useful or necessary to expose a device’s unique identifier to the web platform. The following guidelines will help ensure that this is done in a consistent and privacy-friendly way:

Limit identifiable information in the id

As much as possible, device ids exposed to the web platform should not contain identifiable information such as branding, make and model numbers, etc. In many cases using a randomized number or unique id is preferable to a generic string identifier such as "device1".

Device ids expressed as numbers should contain sufficient entropy so as to avoid re-use or potential sharing among other devices, and should not be easily guessable.

Keep the user in control

Any existing device ids mapped to or stored with the current session by the user agent should be cleared when users elect to "clear their cookies" (and other related settings). Above all, the user should be in control of this potential tracking state and be able to reset it on demand.

Hide sensitive ids behind a user permission

Where device identification does not make sense to be expressed in an anonymous way, access to the identifier should be limited by default. One way to limit exposure is to only surface the identifier to author code after obtaining permission from the user.

Tie ids to the same-origin model

Identifiers should be unique to the origin of the web content that is attempting to access them. Web content from one origin should receive an identifier that is distinct from the identifier given to web content from any other origin despite the physical device being the same.

Within an origin, ids may have a stable representation to web content. This ensures a consistent developer experience if requesting the same device twice.

Persistable when necessary

Device identifiers obtained after a complex or time-consuming device selection process may prefer that author code be allowed to persist the id for use in a later session in order to avoid the selection process a second time. In this case, the API should not only provide a stable id during the session for the given origin, but also be able to deterministically produce the same id in subsequent sessions.

6. Other API Design Considerations

It is important not to neglect other aspects of API design such as privacy, security, accessibility, and internationalization. Please take advantage of these other excellent resources in your design process:

7. Advice on specification writing

This document covers API design for the Web, but those who design APIs are hopefully also writing specifications for the APIs that they design. Some useful advice on how to write specifications is available elsewhere:


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Terms defined by this specification

Terms defined by reference


Normative References

CSS Conditional Rules Module Level 3 URL:
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). URL:
Anne van Kesteren. DOM Standard. Living Standard. URL:
ECMAScript Language Specification. URL:
Ilya Grigorik; James Simonsen; Jatinder Mann. High Resolution Time Level 2. URL:
Anne van Kesteren; et al. HTML Standard. Living Standard. URL:
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL:
Anne van Kesteren. URL Standard. Living Standard. URL:
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL:

Informative References

Anne van Kesteren. XMLHttpRequest Standard. Living Standard. URL: