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 with 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 any retry path.

Use PATCH for partial updates where only provided fields change, which is what clients actually want. PUT requires sending the full object every time, making it fragile for large resources and prone to overwriting concurrent changes.

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 at every layer.

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