api-and-interface-design

Prefer addition over modification: add new fields as optional and never change or remove existing field types. Use PATCH for partial updates, version only when unavoidable, and treat every observable behavior as a commitment under Hyrum's Law.

Pick one error strategy and use it everywhere. A common pattern maps HTTP status codes (400, 401, 403, 404, 409, 422, 500) to a structured body with a machine-readable code, human-readable message, and optional details field.

Validate at system boundaries where external input enters: API route handlers, form submissions, environment variables, and third-party API responses. Internal functions that share type contracts should trust already-validated data instead of re-validating.

Yes, third-party API responses are untrusted data and must be validated before use in logic, rendering, or decisions. A compromised or misbehaving external service can return unexpected types, malicious content, or instruction-like text.

Use discriminated unions when a value has distinct variants with different fields, such as task statuses. A shared discriminator field like 'type' enables compiler-checked narrowing in switch statements, making invalid states unrepresentable.