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.