api-and-interface-design

Define the contract first with typed schemas, then evolve it by only adding optional fields rather than changing or removing existing ones. Use PATCH for partial updates, paginate list endpoints from the start, and keep error responses in one consistent format.

Use a single structured error shape with a machine-readable code, human-readable message, and optional details object. Map errors to standard HTTP status codes like 400, 401, 403, 404, 409, and 422, and never mix patterns like throwing, returning null, and returning error objects across endpoints.

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.

Yes, third-party API responses are untrusted data and must 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 discriminated unions when an entity has multiple variants with different fields, such as task statuses like pending, in_progress, or completed. A shared type tag enables compiler-checked narrowing in switch statements so each variant's fields are accessed safely.

REST URLs should use plural nouns for resources, like GET /api/tasks, because HTTP methods already express the action. Verb-based URLs like /api/createTask duplicate the method semantics and produce inconsistent, unpredictable endpoint naming.