api-and-interface-design

The API and Interface Design skill focuses on guiding developers to create stable, predictable, and well-documented interfaces. It addresses the common challenges of interface misuse, version conflicts, and unclear contracts between system components. By providing clear principles for designing APIs, module boundaries, and frontend-backend interactions, this skill helps teams avoid errors caused by ambiguous or inconsistent interfaces and ensures that systems evolve safely over time.

This skill emphasizes several key capabilities. It promotes a contract-first approach, defining the interface specification before implementation, ensuring clarity and consistency. It enforces uniform error semantics to make API behavior predictable for consumers. Boundary validation ensures that external inputs are properly checked while internal code can be trusted. The skill also instills awareness of Hyrum's Law, reminding designers that all observable behavior becomes an implicit contract once users rely on it, and encourages adherence to the One-Version Rule to prevent dependency conflicts. These features collectively support the creation of APIs and modules that are robust, maintainable, and easy to evolve.

Ideal use cases include designing new REST or GraphQL endpoints, defining module boundaries between teams, creating component prop interfaces, and shaping database schemas that inform API design. Target users are software engineers, API designers, frontend and backend developers, and technical leads responsible for system architecture. This skill is particularly valuable for teams seeking to maintain long-term stability in public interfaces, reduce integration errors, and ensure that changes to APIs or modules do not inadvertently break dependent systems.