What problem does it solve?
This Skill guides the design of stable, well-documented interfaces for APIs and modules, ensuring that the right thing is easy and the wrong thing hard.
Core Features & Use Cases
- Hyrum's Law: Encourages intentional design to avoid unintended dependencies on public behaviors.
- One-Version Rule: Avoids diamond dependency problems by designing for a single version of dependencies.
- Contract First: Defines the interface before implementing it to ensure a clear spec.
- Consistent Error Semantics: Picks one error strategy and uses it everywhere for predictability.
- Validate at Boundaries: Trusts internal code and validates at system edges where external input enters.
- Prefer Addition Over Modification: Extends interfaces without breaking existing consumers.
- Predictable Naming: Provides naming conventions for REST endpoints, query params, response fields, boolean fields, and enum values.
- REST API Patterns: Offers guidelines for resource design, pagination, filtering, and partial updates.
- TypeScript Interface Patterns: Recommends using Discriminated Unions, Input/Output Separation, and Branded Types for IDs.
- Common Rationalizations: Addresses common misunderstandings about API design.
- Red Flags: Lists potential issues in API design to avoid.
- Verification: Provides a checklist for verifying API design.
Quick Start
To begin designing an API, use the 'api-and-interface-design' skill and follow the guidelines for Hyrum's Law, the One-Version Rule, and Contract First principles.
