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 an Idempotency-Key header derived from an immutable identifier like an order ID, then claim it atomically with a unique database constraint before executing the side effect. Reject reused keys with different payloads and store the response for safe replay.

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.

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.

Retries spike exactly when dependencies are degraded, and a timeout leaves the outcome unknown. No queue guarantees exactly-once delivery across a consumer crash, so design for at-least-once delivery with idempotent processing.

Prefer the One-Version Rule: extend interfaces additively rather than forking versions, since multiple versions multiply maintenance cost and create diamond dependency problems. Plan deprecation at design time for anything you must eventually remove.