APIs as ladders

January 24, 2022

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 blogpost by Michelle Bu.

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.

Continue reading →

The secondary market in gift cards

December 13, 2021

This post by patio11 covers a few things that I learned working with gift cards over the years.

Continue reading →