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 the client's intent, then claim it atomically using a database unique constraint rather than a check-then-insert. Guard the payload with a request hash so a reused key with a different body fails loudly, and set key retention to outlive the longest retry path.

Validation belongs at system boundaries: API route handlers, form submissions, external service responses, and environment variable loading. Internal functions that share type contracts should trust already-validated data rather than re-validating.

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.

Use 400 for invalid client data, 401 for missing authentication, 403 for authorization failures, 404 for missing resources, 409 for conflicts, 422 for semantic validation failures, and 500 for server errors without exposing internal details. Pair every status with one consistent error body shape.

Duplicates occur when the key is regenerated per attempt, claimed with a racy check-then-insert, or expired before the longest retry path completes. Timeouts also create an unknown third outcome, so record intent before calling external services.