api-and-interface-design

Design REST APIs for extension rather than modification: add only optional fields, never change existing field types or remove fields, and paginate list endpoints from the start. Define the contract in TypeScript before implementing so the types serve as documentation.

Use one consistent error format across all endpoints: a machine-readable code, a human-readable message, and optional details. Map errors to standard HTTP status codes like 400 for invalid data, 404 for missing resources, and 422 for validation failures.

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

Use PATCH for partial updates where only provided fields change, which matches what clients actually need. PUT requires sending the full object every time and increases the risk of accidentally overwriting fields.

Hyrum's Law states that all observable behaviors of an API will be depended on by someone, regardless of the documented contract. This means every public behavior is a commitment, so avoid leaking implementation details and plan for deprecation at design time.