addy-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 Hyrum's Law means users depend on every observable behavior.

Accept a client-generated Idempotency-Key and claim it atomically using a database unique constraint, not a check-then-insert which races. 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.

Validate only at system boundaries: API route handlers, form submissions, third-party API responses, and environment variable loading. 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, making it fragile for consumers and prone to overwriting fields unintentionally.

Red flags include verbs in URLs like /api/createTask, inconsistent error formats across endpoints, list endpoints without pagination, breaking changes to existing fields, and using third-party API responses without validation. Also avoid idempotency keys derived from UUIDs or timestamps regenerated per attempt.