api-and-interface-design

Prefer addition over modification: add new fields as optional and never change existing field types or remove fields. Define the contract first with typed input and output schemas, and plan for deprecation at design time since users depend on all observable behavior.

Use one consistent structured error body everywhere with a machine-readable code, human-readable message, and optional details. Map HTTP status codes predictably: 400 for invalid data, 401 for authentication, 404 for missing resources, 422 for validation failures, and 500 for server errors.

Use PATCH for partial updates where only provided fields change, which is what clients actually want. PUT requires sending the full object every time, making it fragile for large resources and prone to overwriting concurrent changes.

Validate at system boundaries only: API route handlers, form submissions, environment variables, and third-party API responses, which should always be treated as untrusted. Internal functions sharing type contracts should trust already-validated data.

Paginate list endpoints from the start, not later. Once any user accumulates 100 or more items, unpaginated lists cause performance problems, and adding pagination afterward is a breaking response-shape change for existing consumers.