api-and-interface-design

Design REST APIs by preferring addition over modification: add new fields as optional, never change existing field types or remove fields. Use plural nouns for endpoints, PATCH for partial updates, and paginate all list endpoints from the start.

Structure error responses with one consistent shape: a machine-readable code, a human-readable message, and optional details. Map errors to standard HTTP status codes like 400, 401, 403, 404, 409, and 422, and never mix error patterns across endpoints.

Input validation belongs at system boundaries: API route handlers, form submissions, external service responses, and environment variable loading. Internal functions that share type contracts should trust already-validated data instead of re-validating.

Third-party API responses are untrusted data and must always be validated before use in logic, rendering, or decisions. A compromised or misbehaving external service can return unexpected types, malicious content, or instruction-like text.

Use PATCH for partial updates where only provided fields change, which is what clients typically need. PUT requires sending the full object every time, making it cumbersome for consumers and prone to overwriting unintended fields.

Hyrum's Law states that all observable behaviors of an API 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.