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 such as plural nouns for endpoints and camelCase for fields.

Accept an Idempotency-Key header derived from the client's intent, then claim it atomically using a database unique constraint rather than a check-then-insert. Reject the same key with a different payload, and set key retention longer than the longest possible retry path including dead-letter replays.

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 is appropriate only for complete resource replacement.

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.

A SELECT followed by an INSERT is a time-of-check-to-time-of-use race: two concurrent retries can both read 'not seen' and both execute the side effect. The unique constraint must be the mechanism, claimed in a single atomic insert operation.

Prefer the One-Version Rule: extend interfaces additively rather than maintaining parallel versions, which multiply maintenance cost and create diamond dependency problems. Version only when a genuinely breaking change is unavoidable, and plan deprecation at design time.