How to deal with complex APIs

Some APIs, like the reduce method on JavaScript arrays, are complex by design, but we can make them a lot simpler.

Published in

codeburst

8 min readJun 8, 2018

Some APIs are inherently complex. They may look simple on the surface, and you may think writing those two lines of code may not be a big deal. Under the surface, though, they force you to handle multiple concerns at once, and that usually obscures your intent, making the code harder to read and modify.

In this article, we are going to look at a JavaScript API, Array.prototype.reduce(), and discover how, with a little bit of abstraction, we can make it a lot simpler. We will then try to draw conclusions that can be applied to just about any API you need to deal with.

Right off the bat, I imagine at least some of you might protest: “Array.prototype.reduce() is not complex at all, it’s quite simple!”

I’ll address that concern (pun intended) by giving you a very specific definition of complexity that we’ll use for our article:

Complexity of an API is determined by the number of concerns we need to address simultaneously when using it.

In this sense, Array.prototype.reduce() is complex, even if it’s a lot simpler than imperative loops, and even if implementations using it are only going to be a few lines long.

You will find it easier to follow the examples if you are somewhat familiar with ES6/7 syntax, specifically rest spread, dynamic keys, and the like. I will not provide in-depth commentary on the syntax itself.

Example

Let’s take a look at an example of reduce() usage first.

const toTrueProps = propNames => 
  propNames.reduce(
    (out, propName) => ({ ...out, [propName]: true }), 
    {}
  )toTrueProps(['foo', 'bar']) 
// => { foo: true, bar: true }

The toTrueProps() function starts with an empty object, and for each property name in propNames array, creates a property that has a value true. (It may seem useless, but it comes from a real-life use case that was required by a Vue.JS API.)

reduce() is a very versatile function that can be used in many different scenarios. If you remember the single responsibility principle, you know that a function should do one thing and one thing only. (Actually it says ‘class’ in the original version, but we do functional programming, so we just substitute the word ‘class’ with ‘function’ everywhere! 😋) Because of the versatility of the reduce() function, the function we pass to it, sometimes has to do more than one thing, and that’s not good.

Let’s take a look at what our function does:

it decides what the property should be called, and what it’s value would be
it merges the new property into the output object out

(How do we know how to identify those concerns? First of all, there are many ways to look at it. Secondly, to be completely honest with you, I did it on a hunch. When I first noticed I could do this type of refactoring, it was by accident. I just analyzed some function and refactored it a few different ways to arrive at the best possible factorization that I could come up with. After that I simply try refactoring things in a similar effect, and I know what I’m looking for when I see it. I’m not always successful on the first try either. I’m not sure that part is readily teachable. What’s important is that we know it can be done.)

Back to our article, we now know the function has two concerns intertwined together, or ‘complected together’ as Rich Hickey would put it.

How do we disentangle them?

Disentangling the concerns

In complete vacuum, let’s first express the two concerns in some JavaScript:

const toTrueProp = propName => ({ [propName]: true })const merge = (out, propVal) => ({ ...out, ...propVal })

The toTrueProp() creates an object that has only the property that matches the supplied name and has a value of true.

The merge() function takes the output object, and the fragment that should be merged into it, and merges them together.

You will notice that these two functions aren’t of equal importance. The first one is more specific to the problem we are solving, and the merge() function is a bit more generic. In fact, it’s simply another way of saying Object.assign().

Composing the two concerns

Instead of combining the two functions back into one, we will now compose them. In other words, we want to combine the effects of the two functions without merging the code.

We’ll write a small helper function for this purpose.

const reduceWith = (init, reducer, transformer, xs) => 
  xs.reduce((out, x) => reducer(out, transformer(x)), init)

The new reduceWith() function takes four arguments:

the initial value passed to Array.prototype.reduce()
a reducer() function which takes two values and somehow combines them into a single value
a transformer() function which transforms (or maps) a single element of the array into a form that’s suitable for reducing
the array itself

The order of the arguments is intentional, and we’ll get back to that a bit later.

We use the new function like this:

const toTrueProps = xs => reduceWith(
  {},
  Object.assign, 
  toTrueProp, 
  xs
)

Reusing the generic parts

I did mention the argument order in reduceWith() earlier. The order is not arbitrary. They are ordered from generic to specific.

The first two arguments are more generic, and describes the process of reduction. The second two arguments are specific to the values we are working with in this particular case.

When we partially apply this function, we are more likely to bind the generic arguments first, and almost never bind the specific ones. As Function.prototype.bind() cannot skip arguments, their order plays a big role in our ability to reuse the function by using partial application.

To give you an example, let’s simplify our function even further by creating a variant of reduceWith() with some of the generic parts specified ahead of time:

const reduceToObject = reduceWith.bind(null, {}, Object.assign)

Now we can say:

const toTrueProps = xs => reduceToObject(toTrueProp, xs)

Suddenly, we are left with just the part that’s specific to our problem, and hopefully our original intent now shines through the code. The noise such as Object.assign() and an empty object are gone and replaced by reduceToObject() which clearly demonstrates what the end result will be.

How universal is our reduceWith() implementation? Let’s try it out.

const add = (x, y) => x + yconst identity = x => xconst sum = xs => reduceWith(0, add, identity, xs)sum([1, 2, 3]) // => 6

(Note: The sum() example is an overkill in this case, and I simply used it for the lack of a better example, to demonstrate that reduceWith() is, indeed, generic, and applicable to arbitrary use cases.)

More is less

We went to great trouble (relatively speaking) of writing our own abstractions on top of Array.prototype.reduce(). We ended up with an API that has more arguments, and more thing to think about. So how is this any simpler than the original?

In general terms having more things is not an indication of complexity. We took a single complex thing, and broken it down into multiple simple things. Rather than having to deal with one complex issue all at once, we are now able to deal one simple thing at a time.

When breaking things down, we had to label things so we can refer to them. This presents us with an opportunity to make our intent clearer by naming things. For example, compare reduceWith({}, Object.assign, ...) to reduceToObject(...).

Even though the initial increase in the number of functions is quite noticeable, we also managed to produce multiple functions that are generic and reusable. This helps us reduce (pun intended) the number of functions we have to write in future, and, more importantly, reduces the number of low-level functions, theoretically leading to less bugs.

Because the function is now well factored, and composed using generic data types, the overall code is now a bit safer to modify. We can modify one of the function without fear that it would break the other one so long as we are returning the same simple data. As the return value does not have complicated constraints, it is easy to satisfy this condition.

Testability is also improved thanks to better factoring and overall simplicity of individual functions.

All this is not specific to Array.prototype.reduce(). We can use this technique everywhere. For example, when sorting strings alphabetically, we can split the problem into the one of (A) converting elements into numbers, and then (B) comparing two numbers. Both of these problems can be considered and dealt with in isolation.

This may not come as a surprise to you, but I should mention that we may also run into cases where more than two concerns are intertwined together, and the same rules apply.

A note on reuse

We mentioned code reuse as one of the benefits of spending some time simplifying our APIs. I believe it is important not to gloss over that point. Even though it is somewhat outside the scope of this article, I will still mention a few things.

In order to keep things simple, we made sure our functions are working with simple data types (e.g., plain objects, numbers, strings), rather than complex custom data types. Our reduceToObject() function is possible because we are using plain objects, and can therefore leverage Object.assign().

This point generally applies to all our efforts to disentangle our APIs. High level of reuse is only possible if you use simple types that are already well supported by the language, its standard library, and 3rd party libraries such as lodash and Ramda. If you insist on custom data types, you may lose the ability to leverage them.

When we say custom data types, it’s a bit broader than the strict technical sense. For the purposes of this article, we also include arrays that are used as tuples, or objects with specific keys that have special meaning to the API. In other words, it’s about being semantically custom. To demonstrate this point, let’s rework our code and use a tuple.

// const toBooleanProp = propName => ({ [propName]: true })
const toBooleanProp = propName => [propName, true]// const merge = (out, propVal) => ({ ...out, ...propVal })
const merge = (out, [key, val]) => ({ ...out, [key]: val })

The new code may seem cleaner at first glance, but the merge() function is no longer behaving like Object.assign(), and therefore a bit less generic. Not only does it require us to pass arrays of specific length and element order, but it can now only handle single key-value pairs. This is a trade-off we may sometimes need to make, but we generally want to err on the side of writing generic code and only compromise to make code simpler and clearer.

✉️ Subscribe to CodeBurst’s once-weekly Email Blast, 🐦 Follow CodeBurst on Twitter, view 🗺️ The 2018 Web Developer Roadmap, and 🕸️ Learn Full Stack Web Development.