api-and-interface-design

Design additive-only changes: add new optional fields instead of modifying or removing existing ones. Use contract-first development to define typed interfaces before implementation, and plan deprecation paths for anything consumers already depend on.

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: API route handlers, form submissions, external service responses, and environment configuration. Internal functions that share typed contracts should trust already-validated data rather than re-validating.

Use PATCH for partial updates where clients send only the fields that changed. PUT requires the complete object on every request, which is rarely what clients actually need and increases the risk of overwriting concurrent changes.

Third-party responses are untrusted data that may contain unexpected types, malicious content, or instruction-like text from compromised services. Always validate their structure and content before using them in logic, rendering, or decisions.