api-and-interface-design

To prevent accidental API compatibility breaks, define and lock explicit interface contracts before implementation. This ensures inputs, outputs, validation, error semantics, and versioning remain intentional and reviewable for all downstream consumers.

Hyrum's Law in interface design identifies accidental observable behaviors that downstream consumers depend on. Systematic Hyrum's Law reviews help teams surface these hidden promises and decide whether to document, hide, or remove them before deployment.

Design a contract-first REST API or CLI by drafting explicit contracts that name consumers, enumerate inputs and outputs, specify boundary validation, and describe migration strategies for breaking changes before writing any code.

Yes, this interface design approach works for webhooks and SDK surfaces. It applies to public HTTP APIs, CLIs, and cross-team integration points, ensuring stable field names, response shapes, and error semantics across all integration boundaries.

The best way to handle validation at a trust boundary is to explicitly define error envelopes and exit codes within the interface contract. This locks error semantics and ensures compatibility during future versioning or migration changes.

You should define versioning and migration strategies for your public API during the initial design and change planning phases. Establishing these strategies before implementation prevents accidental compatibility breaks when introducing breaking changes.