Part 2
Usable API design

Now that you have finished the first part of this book, you are able to identify an API’s real goals and represent them as a programming interface, all while having the consumer’s perspective in mind and avoiding the provider’s. This is a solid basis for designing an API that does the job—but people expect more from APIs than just doing the job. An API is worth nothing if it is not usable. The more usable an API is, the less effort is required to work with it, and the more people may choose to use it. They even may love to use it. Usability is what distinguishes awesome APIs from mediocre or passable ones.

Usability is vital for any API, as for any everyday object. Do you remember the Kitchen Radar 3000? Its interface was terrible because it simply exposed inner workings. Unfortunately, such a terrible design can be achieved when creating APIs, even when avoiding the dreaded provider’s perspective! Fortunately, fundamental principles of usability can be learned by observing everyday things.

When people use an everyday object, they want to achieve their goals without being overwhelmed by an abundant but fuzzy set of functions. And they love to think that they are smart because they can discover everything about an object by themselves. It is the same for APIs.

Consumers don’t want to have to think when they use APIs; they want APIs with a straightforward design that lets them achieve their objectives instantly, without having to lose time understanding data, goals, or error feedback. They also want concise and organized sets of goals, not an overwhelming, gigantic, motley API. And, most importantly, they want to feel at home when they use an API; they want to have a feeling of déjà-vu because the API tells them everything, and its design also conforms to standards or common practices.