api-and-interface-design

Design REST APIs for extension by adding only optional fields, never changing or removing existing ones. Use plural-noun resource URLs, PATCH for partial updates, and pagination on list endpoints from the start so growth never forces a breaking change.

Implement idempotency keys by inserting the key in one atomic operation guarded by a unique constraint, then storing the result against it. Reject the same key with a different payload, and set key retention longer than the longest retry path including dead-letter replays.

Input validation belongs at system boundaries: API route handlers, form submissions, environment loading, and third-party response parsing. Internal functions that share type contracts should trust already-validated data rather than re-validating.

Use PATCH for updates because it accepts partial objects and only changes provided fields. PUT requires sending the full object every time, which is fragile for clients and increases the risk of overwriting concurrent changes.

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.