Aaron Hipple

There are a huge number of "principles" that guide API design – I can't begin to list them all exhaustively. Just for a taste, I'll list a few that I'll discuss again in a moment:

The Single Responsibility Principle

that a given unit of software should be responsible for just one thing and not overlap in its responsibilities with other units any more than necessary.

The Principle of Least Astonishment

that a given unit of software should act exactly as expected and not surprise us with unexpected results (direct or otherwise).

The Fail-Fast Principle

that a given unit of software should fail explicitly before producing unexpected results.

The Principle of Loose Coupling

that units of software should be isolated from one another and interact with clarity through few interconnected channels. There shouldn't be a lot of moving parts between them.

In the real world, we often find ourselves weighing one principle against another – often we must simply do the best we can. They're not hard-and-fast rules, but they serve as really useful heuristics at all levels of software design.

A web component may be thought of as an object with its own API. Lots of variations exist, but the abstract concept generally holds. Let's make a simple Riot.js tag.

<counter>
  <div>{ count }</div>
  <button onclick="{ addOne }">+1</button>
  <button onclick="{ subOne }">-1</button>

  <script>
    this.count = 0;
    this.addOne = () => ++this.count;
    this.subOne = () => --this.count;
  </script>
</counter>

We've defined here three primary endpoints to our component's API.

• count is a number property representing the current count.

• addOne is a function allowing us to increase the count by one.

• subOne is a function allowing us to decrease the count by one.

At first glance this seems like a simple and consumable API – but is it robust to change? Imagine that we're now required to communicate the count to and from a server. How do we do this with a minimum of fuss?

Often we'll do this by simply wrapping another API with our own. We might first refactor our view to use a "getter" to the extent it helps us better isolate our internal API from the remote API's changes (embracing the principles of least astonishment and loose coupling).

this.addOne = () => this.setCount(this.getCount() + 1);
this.subOne = () => this.setCount(this.getCount() - 1);
this.getCount = () => apiConnection.getCount();
this.setCount = n => apiConnection.setCount(n);

From the perspective of our users (who we may imagine are the API consumers) our original API is unchanged save for getCount, which is now a method call rather than a property. Had we wrapped it that way in the first place, we wouldn't have been required to alter our markup at all.

Functions have an API as well. The API of a function is most immediately described by encompassed by its arguments and its return value, though it may be embellished in other ways. For example, in many languages functions can modify external state, or they may be bound to an execution context (this).

Even without these complicating factors, a function's API can be complex. Let's imagine a couple of pure arithmetical functions defined like so:

const sum = (x, y) => x + y;
const sumAll = (...xs) => xs.reduce(sum, 0);

These functions are called in similar fashion, and under some circumstances return the same thing.

sum(1, 2);    // 3
sumAll(1, 2); // 3

There are key differences, though. sumAll will still return a numerical value when given zero or one argument(s).

sum();    // NaN
sumAll(); // 0

sum(1);    // NaN
sumAll(1); // 1

sumAll will also operate on more than two arguments.

sum(1, 2, 3);    // 3
sumAll(1, 2, 3); // 6

Both functions will operate on non-numerical values.

sum("foo", "bar");    // "foobar"
sumAll("foo", "bar"); // "0foobar"

sum(3, null, x => x);    // 3
sumAll(3, null, x => x); // "3x => x"

Clearly we've got some problems.

• They don't fail-fast. On being given invalid outputs they return nonsensical (astonishing) results or worse yet, simply wrong results that are still usable. They're likely to create logical errors down the line.

• sum, being a function that can concatenate strings as well as add numbers, seems to be in violation of the single responsibility principle. In addition, their responsibilities overlap, and may not be sufficiently clarified.

• The functions are tightly coupled. sumAll's definition depends directly on sum, which we know to be unreliable.

We can address some of these issues by firming up sum's API. We'll introduce some type checking prior to executing the function and throw an exception if it fails.

const sum = (x, y, ...zs) => {
  if (isNaN(x) || isNaN(y) || zs.length > 0) {
    throw new Error(
      "sum requires exactly two numerical arguments."
    );
  }
  return x + y;
};

By throwing errors on receiving any inputs other than two numbers, we've resolved a couple of major problems with sum:

• It it now more fail-fast than it was – it throws a runtime error rather than producing invalid output. This doesn't help us when we write the code, but it does help us debug incorrect usages and prevent a cascading error that manifests as a harder-to-find bug.

• It can no longer be used to concatenate strings. We're better obeying the single responsibility principle.

With that done, we'll tune up sumAll to address JavaScript's own surprises (Array.prototype.reduce passes more than two arguments to its callback – somewhat surprising, given the type signature of a typical reduce function.)

const sumAll = (...xs) => xs.reduce((x, y) => sum(x, y), 0);

We didn't resolve the coupling issue with sumAll, but now that sum presents a more consistent and predictable API, the ramifications of tight coupling are of less concern. For now we'll prefer that to duplicating the error checking code.

Overkill? Maybe, but software tends to grow and be used in ways that make the extra effort of really designing and documenting even small functions worthwhile.

What if we had tools to help us clarify our APIs? As developers, isn't it our business to find ways to automate problem solving? Why should we have to solve these fundamental problems again and again?

In general, these are the sorts of problems that a strong, expressive type system aims to resolve. Such a system can embed a lot of useful information about an API into the software such that the interpreter can make certain guarantees about the software's behavior.

const sum = (x: number, y: number): number => x + y;
const sumAll = (...xs: number[]): number => xs.reduce(sum, 0);

sum = (+)
sumAll = foldl (+) 0

sum :: Num a => a -> a -> a
sum x y = x + y

sumAll :: (Foldable t, Num b) => t b -> b
sumAll xs = foldl sum 0 xs

sum ::        -- sum...
  Num a =>    -- ...for any `a` which is numerical...
  a -> a -> a -- ...takes two arguments of
              -- type `a` and returns a value of type `a`.

sumAll ::                 -- sumAll...
  (Foldable t, Num b) =>  -- ...for any `t` which is foldable
                          -- and any `b` which is numerical...
  t b -> b                -- ...takes a `t` containing type `b`
                          -- and returns a value of type `b`.