api-and-interface-design

Design REST APIs for extension rather than modification: add only optional fields, never change existing field types or remove fields. Use plural nouns in URLs, paginate all list endpoints, and support PATCH for partial updates so clients send only what changes.

Implement idempotency by inserting the key with a unique constraint in one atomic operation, never a check-then-insert. Derive keys from immutable identifiers like order IDs, reject reused keys with different payloads, and set retention longer than the longest retry path including dead-letter replays.

Validation belongs at system boundaries: API route handlers, form submissions, environment variable loading, and third-party API response parsing. Internal functions sharing type contracts should trust already-validated data rather than re-validating at every layer.

Use PATCH for updates because it accepts partial objects, changing only provided fields. PUT requires clients to send the full object every time, which creates race conditions and forces clients to track fields they do not intend to modify.

Hyrum's Law states that all observable behaviors of an API will be depended on by somebody, including undocumented quirks and error message text. It means every public behavior is a de facto commitment, so design intentionally about what you expose and plan deprecation at design time.

Never trust third-party API responses; always validate their shape and content before use. A compromised or misbehaving external service can return unexpected types, malicious content, or instruction-like text that corrupts your logic or rendering.