Everything I know about good API design
September 16, 2025
Most of what modern software engineers do1 involves APIs: public interfaces for communicating with a program, like this one from Twilio. I’ve spent a lot of time working with APIs, both building and using them. I’ve written public APIs for third-party developers, private APIs for internal use (or consumption by a single frontend page), REST and GraphQL APIs, and even non-network interfaces like the ones for command-line tools.Like designing good software systems, I think much of the advice floating around about API design is too fancy. People get wrapped up in what “real” REST is, or whether HATEOAS is a good idea, and so on. This post is my attempt at writing down everything I know about designing good APIs.
As developers, we may not write APIs if we often if at all, but we work with them every day.
So it’s worth thinking a bit about what makes for good API design, even if you are rarely ever going to do it yourself.
