Designing good APIs

APIs are promises to callers

An API is the part of your code that other people call. In this lesson, that means your JavaScript functions, classes, and modules. The person who writes the call is the caller. The API is everything the caller can see and depend on:

• the names,
• the arguments it takes,
• the value it returns,
• the errors it throws,
• how it changes from one version to the next.

An API is not only a web address on a server. Any function that someone else calls is an API. The line of code where they call it is the call site.

JavaScript's built-in tools are good models to copy:

• addEventListener(type, listener, options) takes the values it needs first, then an object of extra choices last.
• fetch(url, init) does the same: the address first, then an object of choices.
• Array methods use short, clear verbs, like map, filter, and find.

Your own APIs should feel just as familiar.

This lesson uses ideas from functions basics, parameters, destructuring, and coding style. These lessons are related too: iteration protocols, custom errors, creational patterns, types for JavaScript, and npm and version numbers.

A positional argument list means the caller passes values in a fixed order. The order decides what each value means. That is fine for a small helper with two or three values. But public functions tend to grow. Once a function takes several flags, numbers, and strings, a reader can no longer tell which value is which.

The fix has two parts. First, pass the values the function always needs, in order. Then put all the optional choices in one object, called an options object. Each choice in it gets a name.

1function formatPrice(amount, currency, locale, includeTax, taxRate) {2  const taxed = includeTax ? amount * (1 + taxRate) : amount;3  return new Intl.NumberFormat(locale, {4    style: "currency",5    currency,6  }).format(taxed);7}8 9console.log(formatPrice(19.99, "USD", "en-US", true, 0.08));10console.log(formatPrice(19.99, "EUR", "en-US", false, 0.08));

Line 1 says the function takes five values, in this order. Lines 3 to 6 use Intl.NumberFormat, JavaScript's built-in tool that writes a number as money, such as $21.59.

Line 9 works and prints $21.59. But the reader has to remember that true means "add tax" and 0.08 is the tax rate, 8%. Line 10 prints €19.99. It passes 0.08 too, but that value does nothing there: includeTax is false, so no tax is added.

1const defaultFormatPriceOptions = {2  currency: "USD",3  locale: "en-US",4  includeTax: false,5  taxRate: 0,6};7 8const formatPriceOptionNames = ["currency", "locale", "includeTax", "taxRate"];9 10function normalizeFormatPriceOptions(options = {}, warn = console.warn) {11  if (options === null || typeof options !== "object" || Array.isArray(options)) {12    throw new TypeError("formatPrice options must be an object");13  }14  const unknown = Object.keys(options).filter(15    (name) => !formatPriceOptionNames.includes(name)16  );17  if (unknown.length > 0) {18    warn("Unknown formatPrice option: " + unknown.join(", "));19  }20  const settings = { ...defaultFormatPriceOptions, ...options };21  if (!/^[A-Z]{3}$/.test(settings.currency)) {22    throw new TypeError("currency must be a three-letter code");23  }24  if (typeof settings.locale !== "string") {25    throw new TypeError("locale must be a string");26  }27  if (typeof settings.includeTax !== "boolean") {28    throw new TypeError("includeTax must be a boolean");29  }30  if (typeof settings.taxRate !== "number" || settings.taxRate < 0) {31    throw new RangeError("taxRate must be zero or greater");32  }33  return settings;34}35 36function formatPrice(amount, options = {}) {37  if (typeof amount !== "number" || !Number.isFinite(amount)) {38    throw new TypeError("amount must be a finite number");39  }40  const settings = normalizeFormatPriceOptions(options);41  const taxed = settings.includeTax ? amount * (1 + settings.taxRate) : amount;42  return new Intl.NumberFormat(settings.locale, {43    style: "currency",44    currency: settings.currency,45  }).format(taxed);46}47 48console.log(formatPrice(19.99, {49  includeTax: true,50  taxRate: 0.08,51  coupon: "FALL",52}));53console.log(formatPrice(19.99, { currency: "EUR" }));

The function does the same job, but the call is easier to read. Here is what each part does:

• Lines 1 to 6 hold the defaults: the value each option has when the caller leaves it out.
• Line 8 lists the option names the function knows.
• Lines 10 to 20 tidy up the caller's object before it is used. This step is called normalizing. Line 11 throws an error if options is not an object. Lines 14 to 19 warn about any name the function doesn't know.
• Line 20 copies the defaults, then the caller's choices on top. The three dots, ..., copy every property of an object. When both objects have the same name, the later one wins.
• Lines 21 to 32 check each setting. A value of the wrong kind throws a TypeError. A tax rate below zero throws a RangeError. These checks run before any formatting starts.
• Lines 48 to 52 make the call. Each choice has a name. coupon is not a known option, so this call first prints Unknown formatPrice option: coupon, then $21.59.

1function createToast(message, { tone = "info", duration = 3000 } = {}) {2  return { message, tone, duration };3}4 5const saved = createToast("Saved");6const quick = createToast("Saved", { duration: 1000 });7console.log(saved.tone + ":" + saved.duration);8console.log(quick.tone + ":" + quick.duration);

A toast is a small message that pops up for a few seconds, like "Saved". Line 1 uses destructuring: it pulls tone and duration out of the options object, and gives each one a default. The = {} at the end is a default for the whole object. It is used when the caller passes no object at all.

Line 5 passes no options, so both defaults are used. Line 6 changes only duration. Lines 7 and 8 print info:3000 and info:1000. A default is used when the property is missing or is undefined. It is not used for null.

1function createToast(message, { tone = "info" } = {}) {2  return { message, tone };3}4 5createToast("Saved", null);

The = {} on line 1 only steps in when the argument is left out. Line 5 passes null on purpose. JavaScript then tries to pull tone out of null, and throws a TypeError.

So decide what null means for your API, and write it down. Either reject it with a clear message, or treat it the same as "no options". Don't let callers find out from a confusing error.

Option names the function doesn't know need a clear rule too. There are three choices:

• Warn, like formatPrice does. This catches typos, and the rest of the call still works.
• Throw an error. A strict API does this.
• Accept them. Do this only if your API passes extra options on to another tool on purpose, and say so in your documentation.

1function formatPrice(amount, currency, locale, includeTax, taxRate) {2  const taxed = includeTax ? amount * (1 + taxRate) : amount;3  return new Intl.NumberFormat(locale, {4    style: "currency",5    currency,6  }).format(taxed);7}8 9console.log(formatPrice(19.99, "USD", "en-US", true, 0.08));10console.log(formatPrice(19.99, "EUR", "en-US", false, 0.08));

1const defaultFormatPriceOptions = {Run2  currency: "USD",3  locale: "en-US",4  includeTax: false,5  taxRate: 0,6};7 8const formatPriceOptionNames = ["currency", "locale", "includeTax", "taxRate"];9 10function normalizeFormatPriceOptions(options = {}, warn = console.warn) {11  if (options === null || typeof options !== "object" || Array.isArray(options)) {12    throw new TypeError("formatPrice options must be an object");13  }14  const unknown = Object.keys(options).filter(15    (name) => !formatPriceOptionNames.includes(name)16  );17  if (unknown.length > 0) {18    warn("Unknown formatPrice option: " + unknown.join(", "));19  }20  const settings = { ...defaultFormatPriceOptions, ...options };21  if (!/^[A-Z]{3}$/.test(settings.currency)) {22    throw new TypeError("currency must be a three-letter code");23  }24  if (typeof settings.locale !== "string") {25    throw new TypeError("locale must be a string");26  }27  if (typeof settings.includeTax !== "boolean") {28    throw new TypeError("includeTax must be a boolean");29  }30  if (typeof settings.taxRate !== "number" || settings.taxRate < 0) {31    throw new RangeError("taxRate must be zero or greater");32  }33  return settings;34}35 36function formatPrice(amount, options = {}) {37  if (typeof amount !== "number" || !Number.isFinite(amount)) {38    throw new TypeError("amount must be a finite number");39  }40  const settings = normalizeFormatPriceOptions(options);41  const taxed = settings.includeTax ? amount * (1 + settings.taxRate) : amount;42  return new Intl.NumberFormat(settings.locale, {43    style: "currency",44    currency: settings.currency,45  }).format(taxed);46}47 48console.log(formatPrice(19.99, {49  includeTax: true,50  taxRate: 0.08,51  coupon: "FALL",52}));53console.log(formatPrice(19.99, { currency: "EUR" }));

A good name tells the caller what a function does before they read any documentation. Some simple rules:

• Functions do work, so name them with verbs: formatPrice, createToast.
• Values are things, so name them with nouns: price, user.
• A boolean is a value that is only true or false. Start its name with is, has, or can: isOpen, hasUser.
• Name lists in the plural: users, items.
• Write names the same way everywhere, for example always in camelCase.
• Don't use short forms like fmtPrc in public names. They are hard to search for and easy to misread.

1// Names tell callers what kind of work happens.2const cache = new Map([["7", { name: "Asha" }]]);3function getCachedUser(id) {4  return cache.get(id);5}6function fetchUser() {7  return Promise.resolve({ name: "New user" });8}9async function loadUser(id) {10  return getCachedUser(id) ?? fetchUser();11}12 13const saved = loadUser("7");14const missing = loadUser("8");15console.log(saved instanceof Promise && missing instanceof Promise);16Promise.all([saved, missing]).then((users) => {17  console.log(users[0].name);18  console.log(users[1].name);19});

Each name hints at how the function works:

• getCachedUser (line 3) reads a saved user from memory and answers right away. A cache is a store of things you already fetched, kept so you don't have to fetch them again.
• fetchUser (line 6) suggests slow work over the network. Here it is a small stand-in that returns a Promise. A Promise is an object that hands you a value later.
• loadUser (line 9) is async, so it always returns a Promise. That is true when the user is in the cache, and when it isn't.

Line 15 prints true: both calls gave back a Promise. Lines 17 and 18 then print Asha and New user. Later you can swap the stand-in for a real network call. Callers won't notice, because loadUser still always returns a Promise.

The table below sums up the naming rules. Read each row as: "for this kind of name, write it like this, and avoid that."

1function parsePage(value) {2  const page = Number(value);3  if (!Number.isInteger(page)) {4    throw new TypeError("page must be an integer");5  }6  if (page < 1) {7    throw new RangeError("page must be at least 1");8  }9  return page;10}11 12for (const input of ["2", "0"]) {13  try {14    console.log(parsePage(input));15  } catch (error) {16    console.log(error.name + ": " + error.message);17  }18}

Line 1 defines parsePage, which turns text like "2" into a page number. It can fail in two ways:

• Line 3: the value is not a whole number. That is the wrong kind of value, so line 4 throws a TypeError.
• Line 6: the value is a whole number, but it is less than 1. The kind is right, but the size is wrong, so line 7 throws a RangeError.

The loop on line 12 tries "2" and then "0". It prints 2, then RangeError: page must be at least 1.

Pick one way to report errors for your whole API, and stick to it. If one function throws errors, the others should throw too. If your module returns an object like { ok, error } instead, do that everywhere.

1function findUserById(users, id) {2  if (typeof id !== "string") throw new TypeError("id must be a string");3  return users.find((user) => user.id === id) ?? null;4}5 6const users = [{ id: "7", name: "Asha" }];7console.log(findUserById(users, "7").name);8console.log(findUserById(users, "8"));9try {10  findUserById(users, 7);11} catch (error) {12  console.log(error.name);13}

Line 2 throws a TypeError when id is not a string. That is a mistake by the caller. Line 3 returns null when the ID is a valid string but no user has it. That is a normal answer, not a mistake.

Line 7 prints Asha. Line 8 prints null. Line 10 passes the number 7, so the function throws. The catch block on lines 11 and 12 prints TypeError.

Method chaining means calling one method right after another: a.one().two().three(). It works when each method returns an object that has the next method. An API built for chaining is called a fluent API. Each method returns this, the same object, or a new object.

Chaining reads well when each call is one step in building something. It hurts when:

• a step quietly changes something somewhere else,
• a step hides an error,
• you need to look at a value halfway through the chain.

1function createRequest(path) {2  const params = new URLSearchParams();3  return {4    query(name, value) {5      params.set(name, String(value));6      return this;7    },8    build() {9      const query = params.toString();10      return query ? path + "?" + query : path;11    },12  };13}14 15const url = createRequest("/search")16  .query("q", "api design")17  .query("page", 2)18  .build();19console.log(url);

Line 2 makes params, a URLSearchParams object. It is a built-in tool that stores name and value pairs for a URL. Line 4 defines query, which stores one pair. Line 6 returns this, the same builder, so you can call .query() on it again. Line 8 defines build, which turns the pairs into the final URL.

Lines 15 to 18 chain the calls. Line 19 prints /search?q=api+design&page=2. In a URL, the space in "api design" becomes +.

An object that builds something step by step, like this one, is called a builder. You can read more about builders in creational patterns. If you don't need repeated steps or a final check, an options object is usually simpler.

A boolean trap is a call like render(el, true) or setVisible(true, false). The reader has to remember what each true or false means. The boolean itself is fine. The problem is a bare true or false in the call, with no name beside it.

1function setVisible(element, visible, animate) {2  const state = visible ? "shown" : "hidden";3  const motion = animate ? "animated" : "instant";4  return element + ":" + state + ":" + motion;5}6 7console.log(setVisible("toast", true, false));8 9function show(element, { animate = true } = {}) {10  return setVisible(element, true, animate);11}12function hide(element, { animate = true } = {}) {13  return setVisible(element, false, animate);14}15 16console.log(show("toast", { animate: false }));17console.log(hide("menu"));

There are three ways out of a boolean trap:

• Use a named option. show("toast", { animate: false }) explains itself.
• Use two functions with clear verbs when the two choices do different jobs: show and hide, or renderStatic and hydrate.
• Put the value in a variable with a clear name first, then pass the variable.

Browser tools give you lists in many shapes. Here are the common ones:

• a real array, like [1, 2];
• a NodeList, the list of page elements that document.querySelectorAll returns;
• arguments, the list of values passed to an old-style function;
• strings, Sets, Maps, and your own objects.

Two words help you sort these out:

• An iterable is anything a for...of loop can walk through. It has a Symbol.iterator method. Arrays, strings, Sets, and Maps are iterable.
• An array-like object has number keys (0, 1, and so on) and a length, but none of the array methods.

Decide which shapes your function accepts. Then turn the input into a real array right at the start, with Array.from or the spread syntax [...input]. Some people say "accept as many kinds of input as you can". That only helps callers if you write down which kinds you accept.

1function toArray(input, { label = "items", acceptStrings = false } = {}) {2  if (input == null) return [];3  if (typeof input === "string" && !acceptStrings) {4    throw new TypeError(label + " must be an iterable of values, not a string");5  }6  if (typeof input[Symbol.iterator] === "function") return Array.from(input);7  if (Number.isInteger(input.length) && input.length >= 0) return Array.from(input);8  throw new TypeError(label + " must be iterable or array-like");9}10 11const arrayLike = { 0: "Ada", 1: "Lin", length: 2 };12console.log(toArray(new Set(["Ada", "Lin"])).join(", "));13console.log(toArray(arrayLike).join(", "));14console.log(toArray("JS", { acceptStrings: true }).join("|"));

Here is what each check does:

• Line 2 turns null or undefined into an empty array.
• Line 3 rejects a string, unless the caller passes acceptStrings: true. Strings are iterable, but each item would be one character. Most list functions want whole items, like users or page elements.
• Line 6 accepts any iterable, such as a Set.
• Line 7 accepts any array-like object.
• Line 8 throws for anything else.

Lines 12 to 14 print Ada, Lin twice, then J|S. If your function accepts only real arrays, say so, and throw right away for anything else.

1function toArray(input, { label = "items", acceptStrings = false } = {}) {2  if (input == null) return [];3  if (typeof input === "string" && !acceptStrings) {4    throw new TypeError(label + " must be an iterable of values, not a string");5  }6  if (typeof input[Symbol.iterator] === "function") return Array.from(input);7  if (Number.isInteger(input.length) && input.length >= 0) return Array.from(input);8  throw new TypeError(label + " must be iterable or array-like");9}10 11const arrayLike = { 0: "Ada", 1: "Lin", length: 2 };12console.log(toArray(new Set(["Ada", "Lin"])).join(", "));13console.log(toArray(arrayLike).join(", "));14console.log(toArray("JS", { acceptStrings: true }).join("|"));

1function sortPrices(prices) {2  return [...prices].sort((left, right) => left - right);3}4 5const prices = [8, 3, 5];6const sorted = sortPrices(prices);7console.log(sorted.join(", "));8console.log(prices.join(", "));

The array method sort changes the array you call it on. So line 2 first copies the prices with [...prices], then sorts the copy. Line 7 prints the sorted copy, 3, 5, 8. Line 8 prints the caller's array, still 8, 3, 5. This matters when another part of the app still uses that array.

Your work on an API doesn't end when the first version ships. Sometimes a name or a list of arguments turns out to be wrong. Then you can deprecate it: mark it as old, and tell callers to stop using it. Callers need time to change their code, so do it gently:

• Keep the old name working as an alias: a second name that calls the new function.
• Warn once, and say what to use instead.
• Update the documentation.
• Write it in the changelog, the list of changes in each version.
• If many callers must change, offer a codemod: a script that rewrites their code for them.

If you must remove the old name, do it in a major release. That is a new version whose first number goes up, like 2.0.0 after 1.4.0. The new first number tells callers that some old code may stop working. Some deprecated APIs are never removed at all.

1function createToast(message, options = {}) {2  const {3    tone = "info",4    duration = 3000,5    dismissible = true,6  } = options;7  return { message, tone, duration, dismissible };8}9 10let didWarnAboutShowToast = false;11function warnShowToastDeprecated() {12  if (!didWarnAboutShowToast) {13    console.warn("showToast(message, isError) is deprecated; use createToast(message, { tone }).");14    didWarnAboutShowToast = true;15  }16}17 18function showToast(message, isError = false) {19  warnShowToastDeprecated();20  return createToast(message, { tone: isError ? "danger" : "info" });21}22 23console.log(showToast("Saved", false).tone);24console.log(showToast("Failed", true).tone);25console.log(showToast("Again", true).tone);26console.log(createToast("Queued", { tone: "success", duration: 1000 }).duration);

• Lines 1 to 8 are the new API, createToast(message, options).
• Line 10 makes a flag, didWarnAboutShowToast, that starts as false.
• Lines 11 to 16 warn only while the flag is still false, then set it to true. So the warning prints once.
• Lines 18 to 21 keep the old function, showToast(message, isError). It warns, then turns the old true or false into the new options object.

Lines 23 to 26 print the warning once, then info, danger, danger, and 1000.

In your documentation, mark the old function with a @deprecated JSDoc tag and link to the new one. JSDoc is a comment above a function that starts with /**. Many editors read it and cross out the old name wherever someone uses it.

1function createToast(message, options = {}) {Run2  const {3    tone = "info",4    duration = 3000,5    dismissible = true,6  } = options;7  return { message, tone, duration, dismissible };8}9 10let didWarnAboutShowToast = false;11function warnShowToastDeprecated() {12  if (!didWarnAboutShowToast) {13    console.warn("showToast(message, isError) is deprecated; use createToast(message, { tone }).");14    didWarnAboutShowToast = true;15  }16}17 18function showToast(message, isError = false) {19  warnShowToastDeprecated();20  return createToast(message, { tone: isError ? "danger" : "info" });21}22 23console.log(showToast("Saved", false).tone);24console.log(showToast("Failed", true).tone);25console.log(showToast("Again", true).tone);26console.log(createToast("Queued", { tone: "success", duration: 1000 }).duration);

1process.emitWarning("showToast() is deprecated; use createToast().", {2  type: "DeprecationWarning",3  code: "DEP_SHOW_TOAST",4});

Browser code warns with console.warn. Node.js packages can use process.emitWarning instead. Give it the type DeprecationWarning and a short code that never changes, like DEP_SHOW_TOAST, so people can search for it.

Either way, add a note to the changelog and say when the old name will go. If you plan to remove it, do that in a major release, as described in npm package management.

Real projects use all of these choices together. One module might offer a function that creates objects, a class, a helper function, and an old alias. There is no single perfect shape. The goal is an API that feels like one team designed all of it.

1function listUsers(team, { limit = 20 } = {}) {2  return team + ":" + limit;3}4 5console.log(listUsers("design"));6console.log(listUsers("design", { limit: 5 }));

Line 5 is the old call, listUsers("design"). It still works and prints design:20. Line 6 uses the new named option and prints design:5. When you add an optional setting, keep the old default the same, so old calls work as before.

1function calculateTotal(items) {2  return items.reduce((total, item) => total + item.price, 0);3}4 5export function createCart() {6  return { items: [] };7}8 9export function addItem(cart, item) {10  return { items: [...cart.items, item] };11}12 13const cart = addItem(createCart(), { name: "Tea", price: 3 });14console.log(calculateTotal(cart.items));

This example is an ECMAScript module: a file that shares code with the export keyword. To run it, save it as a .mjs file for Node.js, or load it as a module in a browser project. Only createCart and addItem are exported. calculateTotal stays inside the file, so callers can't depend on it, and you can change it freely. Line 14 prints 3, the total for a cart with one tea that costs 3.

The table below shows where these choices appear in real projects. Read each row as: "for this kind of code, use this shape, because of this."

Common misconceptions

• "An options object is always better." A value the function always needs should stay easy to see, as its own argument. Use options for choices that are optional, have names, and may grow.
• "Accept every kind of input." Accepting everything can hide bugs. Write down what you accept, and turn it into one shape on purpose.
• "A fluent API is always cleaner." Chaining helps when you build something step by step. But it can hide the values in between, which makes bugs harder to find.
• "Deprecate means delete." Deprecating marks an API as old and tells callers to move on. It doesn't promise the API will be removed. Keep it working while callers change their code.
• "Throwing errors is less friendly than returning them." Both can be friendly if you use one way everywhere and write it down. Mixing the two is the real problem.

The table below compares three ways to shape a function call. Read each row as: "this shape looks like this, fits here, and has this risk."

Key takeaways

• An API is everything other people call in your code: functions, classes, and modules, not only web addresses.
• Put values the function always needs first. Put optional choices, which may grow, in an options object.
• Copy the built-in tools. Keep names, argument order, results, timing (sync or async), and errors the same across your API.
• Chain methods when the steps help. Don't leave bare true or false values in calls.
• Write down which kinds of lists you accept. Remove an old API only in a major release.

This is the last lesson in the design patterns and architecture module. Next comes Build it from scratch. There you will rebuild built-in tools, such as the array methods, to see the promises they make to callers.