api-and-interface-design

Prefer addition over modification: add new fields as optional and never change existing field types or remove fields. Use plural-noun resource URLs, PATCH for partial updates, and paginate all list endpoints from the start.

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 at system boundaries: API route handlers, form submissions, environment variable 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 or misbehaving external service can return unexpected types or malicious content.

Use PATCH when clients should send only the fields they want to change. PUT requires the full object on every request, which is rarely what clients want and increases the risk of accidentally overwriting fields.

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