liveBook · Manning

Api

As explained in Vanilla Web

An API surface is the set of interfaces and operations that software exposes for external use.

An API is the public set of operations and interfaces that software makes available to other code. On the web, that might be a browser capability you call or a contract you design for a component. Start with the job: fetching data, arranging DOM nodes, or letting a page configure a custom element. A framework may wrap those capabilities, but it is not required to use them. section 2.2.1 section 7.5.1

A custom element exposes its interface through attributes, properties, methods, and events. Use attributes for simple values expressed in HTML; their values are strings. Use properties for values such as objects or arrays, methods for actions, and events to notify the host page of changes. CSS custom properties can expose styling choices, while slots let the host supply content. Keep these responsibilities distinct so consumers know how to configure and interact with the element. section 7.5.1 section 7.9

A rating element’s public interface

A page can declare <star-rating value="3"> and JavaScript can read or set its value attribute with getAttribute() and setAttribute(). The element can also expose a JavaScript property such as value. The attribute and property are different ways to access an interface; their behavior must be defined by the component. section 7.9

When using a browser API, check whether it meets the application’s compatibility and security requirements. Build on stable APIs; treat experimental features as optional enhancements. Some older capabilities now require HTTPS or other security conditions. When designing a small library API, prefer a limited set of explicit exports and avoid patching native prototypes, which can cause collisions. section 2.2.1 section 14.1.2

Table 6.3 Most common methods to arrange elements in the DOM
Method Return type Explanation

parent.append(childOrString)

void

Appends one or more nodes or strings as the last children of the parent element.

parent.prepend(childOrString)

void

Inserts one or more nodes or strings as the first children of the parent element.

element.before(nodeOrString)

void

Inserts nodes or strings immediately before the element, as siblings.

element.after(nodeOrString)

void

Inserts nodes or strings immediately after the element, as siblings.

element.replaceWith(nodeOrString)

void

Replaces the element with the given node(s) or string(s).

element.remove()

void

Removes the element from the DOM.

parent.insertBefore(newNode, referenceNode)

Node

Inserts newNode before the referenceNode child of the parent. Classic DOM method.

parent.replaceChild(newNode, oldNode)

Node

Replaces oldNode with newNode in the parent’s children. Returns the replaced node.

parent.removeChild(childNode)

Node

Removes childNode from the parent and returns it.

element.appendChild(childNode)

Node

Appends a node as the last child of the element. Returns the appended node.

element.cloneNode(deep)

Node

Creates a copy of the element. If deep = true, it also copies descendants.

The DOM arrangement methods illustrate a concrete browser API: each named operation specifies where a node or string goes and what it returns. Moving an existing node preserves its state and listeners rather than copying it. section 6.2.10

How Vanilla Web covers it

How deep it goes
Explains concrete component interface choices and browser API compatibility, without descending into browser implementation internals.
Examples
Uses a star-rating element’s attribute and property, DOM arrangement methods, and native Fetch and Cache APIs.
What it assumes
Assumes basic HTML, CSS, and JavaScript syntax while introducing direct use of browser APIs.
What you can do after
Build it from scratch: define a custom element’s public contract with attributes, properties, methods, and events.
How it connects
Links APIs to the DOM, web components, shadow DOM, and ES modules.

Also explained in

Compare how 4 books explain api →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.