Developers have opinions on what a good API1 is, but rarely have a shared vocabulary to describe what makes them good. This essay puts forward one set of considerations (out of many) that we started using at Stripe in 2019 to discuss API design2. You can find some of these concepts interspersed in this excellent

The hard part of an API is not to use it, but to learn it. After learning how the API works, typing out the commands is not hard. But when you first time you encounter an API, a million questions pop into your mind: What is this object for? Is there a parameter for that? Can the API do X? Learning requires effort, but the more the developer learns, the more problems they can solve. We can imagine the developers climbing a ladder where, for every step they take up the “learning ladder”3, the more problems they can solve.

Developers don't want to learn your API, they want to solve a problem and move on. As such, you should try to minimize the amount of learning they have to do4. In a simple domain, you can have an ideal ladder with only one step. Once developers learn that step, the API helps them solve every problem in its domain. The worst ladder makes them learn a lot upfront but then helps them solve comparatively little.

We’ll look at three groups of people that are at different stages of the ladder:

1. Beginners are trying to learn enough to use the API for the first time.
2. Novices are trying to learn enough to solve their second problem 5.
3. Experts are using the API to solve very complicated problems.

And for each of them, different properties of the ladder matter:

1. The more upfront learning beginners need, the more likely they’ll get discouraged. This is represented by the height of the first step in the ladder.
2. If a novice learns a little more and unlocks a lot of new solutions, they’ll be encouraged to learn further. This is represented by the steepness of the ladder.
3. Experts care about the total number of problems they can solve with the API. This is represented by how far to the right the ladder goes.

We are going to evaluate how APIs help at different stages of the ladder:

1. In order to get started, beginners need an API to be convenient.
2. In order to take the next step, novices need the API to be gradual.
3. In order to solve most problems, experts need the API to be flexible.

But for reasons that will become clear later, you should design your APIs in the opposite order: make them flexible first, gradual second, and convenient third.

Flexible APIs can solve a lot of problems