api-and-interface-design

Design backward compatible REST APIs by preferring addition over modification: add new fields as optional rather than changing types or removing fields. Define the contract first, keep naming conventions consistent, and plan deprecation before removing anything consumers depend on.

Use one consistent error strategy everywhere: a structured body with a machine-readable code, human-readable message, and optional details, mapped to HTTP status codes like 400, 404, 409, and 422. Never mix patterns such as throwing, returning null, and returning error objects across endpoints.

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

Hyrum's Law states that with enough users, every observable behavior of your API becomes depended upon, including undocumented quirks. It means you should expose behavior intentionally, hide implementation details, and plan deprecation at design time.

Use discriminated unions when a value has distinct variants with different fields, such as task statuses like pending, in_progress, or completed. A shared type tag enables compiler-checked narrowing in switch statements so each variant is handled explicitly.