Making Your API Feel Like Home
11 Jun 2025One of the most important properties of a good API is its level of consistency.
“Consistency” can mean many things in computer science, but in the context of API design, it typically refers to the consistency of user interfaces. In other words: once part of the API has been learned, how easily can the rest be guessed? Can users successfully combine known elements in new ways, or apply familiar patterns to unfamiliar elements?
Even within that definition, consistency applies to many aspects of an API:
- Naming: do types, methods, and parameters that serve similar roles also have similar names?
- Parameter order: are similar arguments presented in a consistent sequence?
- Usage patterns: for example, are objects thread-safe, immutable, or do they follow a common lifecycle?
All of these contribute to the overall learnability and usability of your API.
Thinking about your API as a kind of user interface opens up useful comparisons.
For example, it reminded me of a blog post by Joel Spolsky—former CEO of Stack Overflow and, before that, an avid blogger—who wrote:
In most UI decisions, before you design anything from scratch, you absolutely have to look at what other popular programs are doing and emulate that as closely as possible. If you’re creating a document editing program of some sort, it better look an awful lot like Microsoft Word […]
That post was written in 2000, when desktop programs like Microsoft Word were the gold standard for rich user experiences. Today, that role has largely shifted to the Web. But the underlying idea still holds: be consistent with your ecosystem.
If you are designing a Java API, align with the conventions of the Java standard library. If your library builds on Spring, follow the way Spring does things. Borrowing from established APIs makes your own API feel familiar, predictable, and comfortable to use.
Even if you personally disagree with some design decisions—for instance, if you believe that prefixing all interfaces with an I is preferable—you are working in an ecosystem where millions of developers have internalized a different convention.
That makes it effectively the right one.
The Broader Lesson
When designing an interface meant for human consumption—whether a graphical UI or a programming API—there is value in following established patterns. Copying popular idioms and styles helps users feel at home. They do not have to learn everything from scratch. Instead, they can transfer what they already know.