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 database unique constraint before executing the side effect. Reject the same key reused with a different payload, and set key retention longer than any retry path including dead-letter replays.

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.

Use PATCH for partial updates where only provided fields change, which matches what clients actually send. PUT requires the full object on every request and is rarely what consumers want for typical update operations.

Hyrum's Law states that all observable behaviors of an API will be depended on by someone, regardless of the documented contract. It means every public behavior is a commitment, so avoid leaking implementation details and plan deprecation at design time.