Start from the caller. Write the usage you wish existed first. If it reads well and the obvious call is the correct one, the design is good.
Make it hard to misuse. Prefer types/enums over stringly-typed flags; make illegal states unrepresentable; require the essential args, default the rest. The easy path should be the safe path.
Keep the surface small. Expose the minimum; hide internals. Every public name is a future maintenance promise. Fewer, well-named entry points beat many overlapping ones.
Be consistent. Match the naming, argument order, and error conventions of the surrounding code so callers can predict it.
Define the contract: inputs, outputs, errors/failure modes, and side effects. Decide how errors surface (exception vs result) and be uniform.
Design for change. Additive evolution (new optional params, new functions) over breaking signatures. If you must break, version it and migrate (see database-migrations / breaking-change discipline).
YAGNI. Don't add parameters or extension points "just in case" — they're surface you'll maintain forever. Add them when a real caller needs them.

Más de este repositorio

mismo repositorio

Catch bad React in your changes — run react-doctor's deterministic scan and fix what it flags

Run a verifiable security scan (vulns, secrets, misconfig) over code you wrote or deps you added, before calling the work done

Drive a real browser verifiably — navigate, snapshot, act BY INDEX, extract; every step provable

Run multi-agent work as ONE provable causal DAG — parallel subagents, an Orchestrate graph, an immutable spec-seed

Author or connect a Model Context Protocol server so an agent gains new tools

Build automated pipelines that gate merges and ship reliably

name	api-design
description	Design interfaces that are clear, hard to misuse, and cheap to change
version	1
trust	built-in

An API (a function, module, endpoint, or library surface) is a contract others depend on. Design the smallest, clearest one that does the job.

Start from the caller. Write the usage you wish existed first. If it reads well and the obvious call is the correct one, the design is good.
Make it hard to misuse. Prefer types/enums over stringly-typed flags; make illegal states unrepresentable; require the essential args, default the rest. The easy path should be the safe path.
Keep the surface small. Expose the minimum; hide internals. Every public name is a future maintenance promise. Fewer, well-named entry points beat many overlapping ones.
Be consistent. Match the naming, argument order, and error conventions of the surrounding code so callers can predict it.
Define the contract: inputs, outputs, errors/failure modes, and side effects. Decide how errors surface (exception vs result) and be uniform.
Design for change. Additive evolution (new optional params, new functions) over breaking signatures. If you must break, version it and migrate (see database-migrations / breaking-change discipline).
YAGNI. Don't add parameters or extension points "just in case" — they're surface you'll maintain forever. Add them when a real caller needs them.