api-designlisted

# API Design ## Purpose An API is a promise. Once something depends on it, changing it costs everyone who depends on it, which is why interface decisions are among the most expensive to reverse. The measure of a good API is not elegance. It is that the obvious way to use it is the correct way, and that misuse is difficult or impossible. ## When to use - Adding a public function, class, module, service endpoint, or plugin interface. - Designing a boundary between subsystems or between teams. - An existing API is consistently misused — which is an API problem, not a user problem. - A change would break existing callers and needs a migration path. - Designing data that content authors or modders will write against. ## When NOT to use - Internal code with one caller that you control. Design it directly; an interface for a single implementation is usually overhead. - Deciding module boundaries themselves. Use `software-architecture` — that decides *where* the boundary goes; this decides *what it looks like*. - HTTP-specific concerns. Use `web-rest-api-design`. ## Required context | Fact | Why it matters | |---|---| | Who the callers are, and their expertise | An API for your team differs from one for modders | | Whether it is public or internal | Determines how expensive a change will be | | Existing conventions in the codebase | Consistency beats individual perfection | | Whether callers can be updated in lockstep | Decides whether breaking changes are affordable |