api-and-interface-design

Define the contract first with typed input and output schemas, then evolve it by adding optional fields only. 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 header and claim it atomically using a database unique constraint, not a check-then-insert. Reject the same key reused with a different payload, and set key retention longer than the longest possible retry path.

Validate only at system boundaries: API route handlers, form submissions, environment variable loading, and third-party API responses. 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 need. PUT requires sending the full object every time and increases the risk of accidentally overwriting fields.

Hyrum's Law states that all observable behaviors of an API will be depended on by someone, regardless of the documented contract. It means every public behavior is a commitment, so avoid leaking implementation details and plan deprecation at design time.