api-and-interface-design

Define the contract first with typed input and output schemas, then extend interfaces only by adding optional fields. 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, then claim it atomically using a database unique constraint rather than a check-then-insert. Guard the payload hash so a reused key with a different body fails loudly, and set retention longer than the longest retry path.

Validation belongs 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 instead of re-validating.

Use PATCH for partial updates where only provided fields change, which is what clients actually need. PUT requires sending the full object every time and increases the risk of accidentally overwriting fields.

Common mistakes include inconsistent error formats across endpoints, verbs in REST URLs, list endpoints without pagination, and trusting third-party API responses without validation. Also avoid accepting idempotency keys without atomically storing and honouring them.