How to Design a Good API and Why It Matters
Central idea
A good API makes the common path obvious, mistakes difficult, and future evolution possible without exposing implementation decisions.
Summary
APIs are among the longest-lived parts of a system, so early design choices become obligations for years. Start from real use cases rather than a proposed solution, write a short specification, and draft client code before implementing. Keep the surface small, make each abstraction do one thing well, and hide representation details. Names, types, defaults, failure behavior, and documentation should guide callers toward correct use. Minimize mutability and fail quickly when a contract is violated.
Key ideas
Design from the caller outward
Example client code exposes awkward flows and missing concepts earlier than implementation work does.
Every exported element is a commitment
A smaller API is easier to learn, test, document, and evolve compatibly.
Make contracts explicit
Document preconditions, postconditions, side effects, exceptions, and concurrency expectations.
A useful quality test
Easy to learn and use.
Hard to misuse.
Readable at the call site.
Flexible enough to evolve.
Why it matters now
Generated client code multiplies whatever affordances an API provides. Clear contracts help both humans and agents produce correct integrations.
Continue with the original
This short version preserves the main argument. Follow the source for the complete talk, article, or book.