HOWTO: make a breaking change to your heavily-used API
Stripe schools us on the right way to do engineering.
We locked ourselves in a conference room for three months with the goal of designing a truly unified payments API. If successful, a developer would only need to understand a few basic concepts in order to build a payments integration. Even if they hadn’t heard of the payment method, they should be able to just add a few parameters to a few specific points in their integration. To enable this, the states and guarantees of our APIs had to be extremely predictable and consistent. There shouldn’t be an array of caveats and exceptions scattered throughout our docs.
A team of five people—four engineers and a PM—walked through every payment method we supported and we could imagine supporting in the future. We iterated on an API design that would be able to model all of them. We ignored all existing abstractions and thought about the problem from first principles.
Stripe was forced into launching a new API because their existing one had too much bolted on and was getting unwieldly. This is a classic way a big, successful company starts to lose what made them great in the first place. But not Stripe! They kept their existing API operating, designed a new one from first principles, and made migrating as easy as possible.