api-and-interface-design

Prefer addition over modification: add new fields as optional and never change or remove existing field types. Define the contract first with typed input and output schemas, and plan for deprecation at design time since consumers depend on all observable behavior.

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 including dead-letter replays.

Use 400 for invalid client data, 401 for unauthenticated, 403 for unauthorized, 404 for missing resources, 409 for conflicts, 422 for semantic validation failures, and 500 for server errors. Pair every status with one consistent structured error body containing a machine-readable code and human-readable message.

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 throughout the codebase.

Use PATCH for partial updates where only provided fields change, which is what clients actually want. PUT requires sending the full object every time and risks overwriting fields the client did not intend to modify.

Prefer the One-Version Rule: extend interfaces additively rather than forking versions, since multiple versions multiply maintenance cost and create diamond dependency problems. Version only when a truly breaking change is unavoidable.