api-and-interface-design

Prefer addition over modification: add new fields as optional and never change or remove existing field types. Define the contract first with typed inputs and outputs, and plan for deprecation at design time since Hyrum's Law means users depend on every observable behavior.

Pick one error strategy and use it everywhere: map HTTP status codes (400, 401, 403, 404, 409, 422, 500) to a structured error body with a machine-readable code, human-readable message, and optional details. Never mix patterns like throwing, returning null, and returning error objects across endpoints.

Validate at system boundaries where external input enters: API route handlers, form submissions, third-party API responses, and environment variables. Do not validate between internal functions that share type contracts or on data from your own database.

Use PATCH for partial updates where only provided fields change, which is what clients actually want. PUT requires sending the full object every time, making it fragile for consumers and prone to overwriting unrelated fields.

Use discriminated unions when a type has multiple variants with different associated data, such as task statuses like pending, in_progress, or completed. A shared discriminator field enables type narrowing in switch statements so consumers handle each variant explicitly.

Third-party responses are untrusted data that can contain unexpected types, malicious content, or instruction-like text from compromised or misbehaving services. Validate their shape and content before using them in logic, rendering, or decision-making.