Chapter 6
Build APIs That Say Just What They Mean

When we read code that’s more verbose than it needs to be, it slows us down. Ideally, we want code with only what’s necessary to communicate its purpose. In this chapter we’ll look at ways to provide beautiful APIs that allow developers to avoid including unnecessary boilerplate in their code. We’re not talking about APIs here in the HTTP web service sense, just the interface that a library or piece of code exposes to let you use it.

This goal may seem a bit hazy, since “beauty” is subjective, and easy-to-use pure-function APIs are already prevalent. The good news is that providing a succinct macro API doesn’t prevent you from offering an API with functions as well. I highly recommend this practice to help out your users who want to avoid the problems we talked about in Chapter 3, ​Use Your Powers Wisely​. The usual workflow is to write the functional API first, and then add a thin macro layer over the top where it’s desirable. Of course, the order in which you do these things matters much less than the end result: offering both a flexible function API and a potentially more pleasant macro API.

In this chapter, we’ll look at a couple of Clojure APIs that you’ve probably interacted with and see how their macros affect the interface that they present.