api-and-interface-design

Prefer addition over modification: add new optional fields instead of changing or removing existing ones. 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 like 400, 401, 403, 404, 409, 422, and 500, and never mix patterns across endpoints.

Validate only at system boundaries: route handlers, form submissions, environment loading, 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 or rendering. 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.

Avoid verbs in URLs, inconsistent error formats, list endpoints without pagination, breaking changes to existing fields, and scattered validation. These create unpredictable contracts that consumers cannot rely on.