api-and-interface-design

Define the contract first with typed inputs and outputs, then evolve it by adding optional fields only. Never change existing field types or remove fields, and follow the One-Version Rule by extending rather than forking the API.

Accept a client-generated Idempotency-Key and claim it atomically with a unique database constraint before performing the side effect. Reject the same key with a different payload, and set key retention longer than the longest possible retry path including dead-letter replays.

Validate only at system boundaries: API route handlers, form submissions, external service responses, and environment configuration. 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 matches what clients actually 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.