tinyhumansai API Design
A public interface is a promise with no expiry. This pass is about the parts that are expensive to undo, not the parts that are easy to argue about.
When to use
- A new endpoint, event, webhook or SDK method is being added.
- An existing one is changing shape in any way a client could notice.
Steps
- Name what cannot change: the resource names, the identifiers, the pagination shape, the error contract. Everything else can be added to later.
- Check it against what exists. An API that is internally consistent and locally sensible is worse than one that is consistent with its neighbours.
- Model the failures, not just the success. What does a client do on a partial write, a rate limit, a retry of something that already landed? An idempotency story decided later is a story clients already got wrong.
- Ask what a client does on the next version. If the answer is "we version the whole API", the design is not finished.
- Write the example first — the smallest complete request and response a developer could copy. An interface whose example is hard to write is hard to use.
- Record the call.
record_entryondecisionswith what was chosen and the alternatives rejected; interface shape is exactly what gets re-litigated six months on.
Output
The interface, its example request and response, its error contract, and a
decisions row naming what was rejected and why. Breaking anything already
public is a person's call, not this pass's.