2013-10-10

Co.Labs

Designing Great APIs Means Valuing Laziness

There are three qualities every great API must have to appeal to the sloth in all of us.



When you’re writing software for other people to use in their applications, designing the API is important. The API is the interface that developers see and work with. Building on top of a great API should feel like building with Lego pieces, everything snapping together perfectly to make a coherent system.

So what makes an API great? An API must appeal to the most powerful emotion for software developers: laziness. There are three qualities every great API must have, to appeal to laziness.

First, an API needs to be intuitive. An API becomes intuitive when it is built up of many smaller parts that all work in a similar way. With an intuitive API, you can be lazy. You don’t have to think hard about how it works. You don’t have to remember complicated details because your intuition correctly explains them. You don’t have to spend a lot of time learning new parts of the API because it all works pretty similarly. A great example is the compound data types in Python. Once you learn how lists work, strings and tuples become intuitive because they work similarly.

Second, an API needs to have great documentation. Great docs let developers be lazier because they make it easy to get simple answers to simple questions. Different types of docs are appropriate for different types of questions. Reference docs make it easy to answer the question of "What does this part of the API do?" Guides or tutorials make it easy to answer the question of "How do I use this API to do a common task?" And a quickstart makes it easy to answer the question of "How do I get started?" A good example is the Stripe API, whose docs are so well-designed that PayPal cloned them.

Finally, an API needs to be opinionated. There are many API design questions with no right or wrong answer. Should method names be separated_by_underscores_like_this or capitalizedLikeThis? In the larger programming community, these questions can turn into eternal debates. The team building your API must have strong opinions on these questions. If you don’t take a stance, then eventually your team will grow, different people will design different sections differently, and your API will cease to feel intuitive. A great example of what not to do is the PHP string library. Learning the PHP string library is like memorizing digits of pi. With no pattern, there’s no lazy shortcut to doing the work of individually memorizing each method.

The overriding principle to all of this is to make life easy for developers. A good API will let you be lazy. A great API will empower you to be really, really lazy.

Kevin Lacker is CTO and cofounder of Parse, which helps developers build mobile and web apps that span across multiple platforms and devices.

[Image: Flickr user Rising Damp]






Add New Comment

1 Comments

  • Daniel Mackay

    I would also add that a good API makes it hard for you use it wrongly.  An example of this is using parameters in a constructor to enforce something gets set up correctly instead of expecting the user to call an initialization or setup method first.