API and Interface Design

Problem it addresses

Once an interface is exposed, response shapes, error semantics, and undocumented behavior become de facto contracts. Common team-level failures include REST endpoints returning different structures under different conditions, unclear contracts for GraphQL, module boundaries, or component props, inconsistent choices between PATCH and PUT, and third-party responses entering business logic without validation. This skill turns those failure modes into a practical design framework.

How the skill works

It organizes interface design around the rule that the right behavior should be easy and the wrong behavior should be hard:
- Contract first: define inputs, outputs, types, and error formats before implementation.
- Consistent error semantics: avoid mixing throw, null, and { error } across endpoints.
- Boundary validation: validate API handlers, form submissions, environment variables, and third-party responses; avoid repeated validation inside trusted internal code.
- Backward-compatible extension: prefer optional additive fields, discriminated unions, branded IDs, and PATCH-friendly updates over breaking changes.
- Predictable naming and REST conventions: use GET /api/tasks, camelCase query parameters, isComplete booleans, and UPPER_SNAKE enum values.
It closes with a checklist covering typed schemas, consistent errors, pagination, PATCH support, and naming consistency.

Where it applies and cautions

This is useful for new API endpoints, cross-team contracts, component props, and database schemas that shape API behavior. It does not replace security scanning, authorization models, or distributed-system design. Treat Hyrum's Law as a design constraint: observable behavior is a commitment, so plan deprecation early.