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 and claim it atomically using a database unique constraint, not a check-then-insert. Store the request hash to reject reused keys with different payloads, and set key retention longer than the longest 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 risks overwriting fields the client did not intend to modify.

Validate only at system boundaries: API route handlers, form submissions, environment variables, and third-party API responses. Internal functions that share type contracts should trust already-validated data rather than re-validating.

No queue guarantees exactly-once delivery across a consumer crash, since the broker acknowledgment and your side effect are not in one transaction. Design for at-least-once delivery with idempotent processing, since retries spike exactly when dependencies degrade.