api-and-interface-design

Design stable REST API endpoints using Contract-First principles and the One-Version Rule. This approach ensures predictability by making the right usage easy and preventing breaking changes, applying Hyrum's Law to maintain robust client compatibility.

Structure consistent API error semantics by enforcing boundary validation and predictable naming conventions. This ensures interfaces fail predictably, making it harder to misuse endpoints while maintaining clear, stable type contracts across system boundaries.

Create type-safe TypeScript interfaces using Discriminated Unions, Input/Output Separation, and Branded Types. These patterns establish strict module boundaries, ensuring predictable data shapes and preventing invalid prop combinations at compile time.

Use specific REST API patterns for resource design, pagination, filtering, and partial updates. These patterns provide standardized, predictable interfaces for managing large datasets and modifying resources without full payload replacements.

Yes, this API design guidance applies to both GraphQL and REST endpoint design. It focuses on universal design principles like Hyrum's Law, stability, and consistency, ensuring type-safe and predictable interfaces regardless of the specific protocol.

Apply Hyrum's Law to interface design whenever you establish module boundaries or component prop interfaces. It addresses common rationalizations by ensuring that all observable behaviors become contractual, preventing unintended dependencies on implementation details.