api-and-interface-design

Define the contract first with typed input and output schemas, then extend interfaces only by adding optional fields. Never change existing field types or remove fields, and follow consistent naming conventions like plural nouns for endpoints and camelCase for fields.

Accept a client-generated Idempotency-Key and claim it atomically using a database unique constraint, not a check-then-insert. Reject the same key with a different payload, decide how in-flight duplicates are handled (409, wait, or 202), and retain keys longer than the longest retry path.

Validation belongs at system boundaries: API route handlers, form submissions, external service responses, and environment variable loading. Internal functions that share type contracts should trust already-validated data rather than re-validating.

Use PATCH for partial updates where only provided fields change, which is what clients typically want. PUT requires sending the full object every time and is better reserved for complete resource replacement.

Hyrum's Law states that all observable behaviors of a system will be depended on by someone, regardless of the documented contract. This means undocumented quirks, error text, and ordering become de facto commitments, so be intentional about everything you expose.

Prefer the One-Version Rule: extend rather than fork, since multiple versions multiply maintenance cost and create diamond dependency problems. Design for additive, backward-compatible changes from the start instead of planning parallel versions.