api-design

API and Interface Design

Design interfaces that are hard to misuse: consistent error shape, additive changes only once a contract ships, and validation only at the boundary where untrusted input enters.

Hyrum's Law

With enough users of an API, every observable behavior becomes a de facto contract — regardless of what the documentation promises.

Undocumented quirks, error text, timing, and field ordering all become things someone depends on once observed. Design implication: don't expose what you're not willing to keep stable, and plan for deprecation at design time, not as an afterthought.

Core rules

1. Contract first. Define the request/response types before implementing the handler.
2. One error shape, everywhere.

   { "error": { "code": "VALIDATION_ERROR", "message": "email is required", "details": {} } }
   

   Never mix throwing, returning null, and returning {error} across different endpoints in the same API — the caller can't predict behavior.
3. Validate at the boundary only. HTTP handlers, form submissions, and third-party API responses are untrusted; internal function calls that already received validated types are not — re-validating there is wasted code that obscures where the real boundary is.
4. Additive changes only, once shipped. New optional fields are safe. Changing a field's type, removing a field, or changing status-code semantics for an existing endpoint is a breaking change — ship it as a new version or a new endpoint, never as a silent modification.
5. Pagination on every list endpoint, from the first version — adding it later is itself a breaking change to response shape.

Gotchas

• A PATCH that silently ignores unknown fields is easy to build and easy to misuse — a client sending a typo'd field name gets no error and no effect, and won't notice until data looks wrong days later. Reject unknown fields at the boundary instead of ignoring them.
• REST resource URLs with verbs (/api/createTask) are a naming smell that correlates with inconsistent HTTP-method semantics elsewhere in the same API — grep for this pattern as a quick signal to review further.
• A third-party API response is untrusted data even when the third party is a well-known vendor: validate its shape before using it in any decision or rendering path.