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.

Use one consistent error shape everywhere: a machine-readable code, a human-readable message, and optional details. Map errors to standard HTTP status codes such as 400 for invalid data, 404 for missing resources, and 422 for validation failures.

Validate only at system boundaries: 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 responses are untrusted data and must be validated for shape and content before use in logic, rendering, or decisions. A compromised external service can return unexpected types or malicious content.

Use discriminated unions when a value has distinct variants with different fields, such as task statuses. A shared discriminator field like 'type' gives consumers automatic type narrowing in switch statements.